Quick links: Content - sections - sub sections
EN FR

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 createapp.php -withcmdline myapp

-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 cmd.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.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 :

  • a jCmdlineCoordinator instead of jCoordinator
  • a jCmdLineRequest instead of de jClassicRequest
  • 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 commands

such a controller can be created using jelix-scripts :


# module foo creation, with a cmdline controller inside
$ php cmd.php createmodule -cmdline foo

or


# create bar cmdline controller inside foo module
$ php cmd.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