eZ publish comes with two classes that are specifically designed to work with command-line interfaces (CLI) and shell scripting.

eZCLI

This is a general class which is found in the eZUtils library, it has lots of functions for handling input and output to CLI.

Usage

Using this class in your scripts is simply to include the PHP file lib/ezutils/classes/ezcli.php and getting the global instance.

Example 1:

include_once( 'lib/ezutils/classes/ezcli.php' );

$cli =& eZCLI::instance();

Printing something to the user is done with the output method, it is similar to print() but will make sure a newline is entered after the line. It will also check the is-quiet flag to see if output is allowed.

Example 2:

$cli->output( "Hello world" ); // Prints "Hello word" with a newline.

$cli->output( "Hello", false ); // Prints only "Hello" without a newline

$cli->output( " World" ); // Prints only " World" with a newline.

eZScript

This is a kernel specific class which deals with proper initialization and shutdown of eZ publish scripts. This class depends on the eZCLI class for several input and output functions.

Usage

Using this class in your scripts is to include the PHP file kernel/classes/ezscript.php and getting the global instance. This should be done after the eZCLI initialization.

Example 1:

include_once( 'kernel/classes/ezscript.php' );

$script =& eZScript::instance( array( 'description' => 'My first test script,

                                     'use-session' => false,

                                     'use-modules' => true,

                                     'use-extensions' => true ) );

As you see here it is possible to tell the class to enable or disable support for some internal eZ publish functionality, here we tell it we don't want sessions but want modules and extension support, and we also give it a description for the help page (-h).

The next step is to start the script code, we do that by calling startup(). If you want to modify some flags in the script object you must do this before this step

$script->startup()

The script object is ready to be configured, typically you will read in user arguments and options now and set some flags based on that information. This is explained in detail in the Option handling document.
If you don't have any special options or arguments you can do.

$options = $script->getOptions();

Before your own code is run the script object must be told to initialize itself based on the current flags and settings, this could be to setup module loading and check extensions.

$script->initialize();

Now that all necessary intialization is done you can start to execute the actual script code. For instance we could do.

$cli->output( "This is a test script" );

$cli->output( "Type " . $cli->stylize( 'emphasize', '-h' ) . " to see what I can do" ); // Highlight -h with a color (if it's enabled).\

When your code is done or you want to quite the script you must shutdown the script properly, simply calling exit won't work and will give you an error from eZ publish. Instead run the shutdown() method, you can even specify an exit code and an error message.

$script->shutdown(); // Normal shutdown, the code will return after this call

$script->shutdown( 1 ); // Ends the script with error code 1, the code will not return

$script->shutdown( 1, "Could not find file $file" ); // Ends in error code 1 and gives information on what went wrong