Quick links: Content - sections - sub sections
EN FR

Introduction

On the server-side, an application needs every now and then 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 would also be well suited for those jobs. Thanks to Jelix, you can develop actions specifically for the command line. As a result, all processings stay 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.

Manually

If your application already exists, just create scripts/cmdline.php at your application root folder. Below, its contents is detailed:


<?php

require_once ('../../lib/jelix/init.php');

require_once ('.././application.init.php');

require_once (JELIX_LIB_CORE_PATH.'request/jCmdLineRequest.class.php');

$config_file = 'cmdline/config.ini.php';

$jelix = new jCoordinator($config_file);
$jelix->process(new jCmdLineRequest());

?>

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 :


$ php jelix.php createmodule -cmdline foo  // module foo creation, with a cmdline controller inside

or


$ php jelix.php -cmdline foo bar // create bar cmdline controller inside foo module

Manually

To create a cmdline controller manually, it is required to inherit from jControllerCmdline instead of jController


<?php

class defaultCtrl extends jControllerCmdline {

    function index() {
        $rep = $this->getResponse(); // response text
        $rep->content = "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/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.

Exemple :


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.

Exemple :


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 jelix~help:index module~controller:action