Chapter: Command line processing
| « Web services | ^ Main concepts | Define commons processes between many actions » |
− Table of content
On the server-side, an application could need to process some jobs silently and perhaps repeatedly. This is often done in shell or perl scripts using cron utility. As PHP is a scripting language, it is also well suited for those jobs.
Thanks to Jelix, you can develop actions specifically for the command line. As a result, all processings are done in the application model and you don't suffer from language switching.
Installation ¶
Three elements are required to execute an action on the command line:
- a specific entry point
- a cmdline controller
- a command line configuration file
Jelix-scripts have some helper tools to create those.
Entry point creation ¶
with jelix-scripts ¶
When you create your application, just add -withcmdline option:
$ php jelix.php createapp -withcmdline
-withcmdline option will tell createapp to create inside a classic application structure, a scripts/ folder containing cmdline.php entry point.
If you already created the application, you can also use the createentrypoint command :
$ php jelix.php createentrypoint -type cmdline myscript
It will create a new entrypoint for command line, named myscript.php in the scripts/ folder.
Manually ¶
If your application already exists and don't want to use jelix-scripts, you just create scripts/cmdline.php/ at your application root folder (you can use an other name than cmdline.php). Below, its contents is detailed:
<?php
require_once ('../application-cli.init.php');
require_once (JELIX_LIB_CORE_PATH.'jCmdlineCoordinator.class.php');
require_once (JELIX_LIB_CORE_PATH.'request/jCmdLineRequest.class.php');
$config_file = 'cmdline/config.ini.php';
$jelix = new jCmdlineCoordinator($config_file);
$jelix->process(new jCmdLineRequest());
?>
Comparing a cmdline entry point to a default web entry point, you find :
- the use of a
application-cli.init.phpfile, which is similar to theapplication.init.phpused for web entry points, but which have some differences, like defining a different temp folder (otherwise some rights problem could arise) - a
jCmdlineCoordinatorinstead ofjCoordinator - a
jCmdLineRequestinstead of dejClassicRequest - a specific configuration file
cmdline/config.ini.php
You have also to update the myapp/project.xml to declare this new entry point, by adding a new <entry> element inside the <entrypoints> element:
<entrypoints>
<entry file="index.php" config="index/config.ini.php" />
<entry file="cmdline.php" config="cmdline/config.ini.php" type="cmdline"/>
</entrypoints>
Controller creation ¶
You have to create a controller dedicated to command line processing.
with jelix-scripts ¶
such a controller can be created using jelix-scripts :
# module foo creation, with a cmdline controller inside
$ php jelix.php createmodule -cmdline foo
or
# create bar cmdline controller inside foo module
$ php jelix.php -cmdline foo bar
Manually ¶
To create a cmdline controller manually, it is required to inherit from jControllerCmdline instead of jController. Here is an example for the controller default.cmdline.php :
<?php
class defaultCtrl extends jControllerCmdline {
function index() {
$rep = $this->getResponse(); // cmdline response by default
$rep->addContent("Hello, it works !");
return $rep;
}
}
?>
Configuration file creation ¶
If you used createapp jelix-script with -withcmdline option, cmdline configuration file has been generated and located here: var/config/cmdline/config.ini.php.
Otherwise, you must create one at the same location. Its content shall be similar to var/config/index/config.ini.php.
Command line actions ¶
To call your cmdline actions, you'll certainly need to pass parameters and/or options
Options ¶
Declaration ¶
If your command accepts options, you should fill the $allowed_options class member, which is an associative array.
protected $allowed_options = array(
'action_name' => array('-option_name' => true/false)
);
if an option name is set to true then the controller action will search a value after it.
Parsing ¶
In your cmdline controller actions, you'll want to parse options passed. Use option('-option_name') method.
Example :
public function myaction_script() {
$myoption = $this->option('-nom_option');
}
Parameters ¶
Declaration ¶
Parameters are declared in a same way as options. Just use $allowed_parameters:
protected $allowed_parameters = array(
'action_name' => array('parameter_name' => true/false)
);
if a parameter name is set to true, then it is required otherwise not.
Parsing ¶
In your cmdline controller actions, you'll want to parse parameters. Use param('-parameter_name') method.
Example :
public function myscript() {
$myparam = $this->param('parameter_name');
}
Help message ¶
Usually a script can generate instructions or an help message for how to use it. $help controller member is for this purpose:
public $help = array(
'action name' => 'help message'
);
Next section will describe how to call a cmdline action and thus how to display this help message.
Cmdline action use ¶
To use your cmdline actions or shall we say scripts, open a console and navigate to your application scripts/ directory.
Then execute cmdline.php followed by an action selector and its relateds options/parameters
Example :
$ php cmdline.php module~controller:action -option_name optionval parameter_value
To display an help message :
$ php cmdline.php help module~controller:action
If you want to have a script dedicated to the default module/action defined in the configuration file of the script, you can add a true parameter to jCmdlineRequest in the entrypoint :
<?php
...
$jelix->process(new jCmdLineRequest(true));
...
?>
So you won't have to indicate the action as parameter of the command. Of course, in this case you cannot execute any other actions. The previous example become:
$ php cmdline.php -option_name optionval parameter_value
And to have the help, no need too to indicate the action:
$ php cmdline.php help
