Plain CLI scripts with eZScript and ezexec #

This page is for PHP developers who maintain command line scripts written as plain files, or who need to run a piece of PHP with the kernel booted. New commands are written as classes (Write a console command); the plain form still runs exactly as before, and every class-based command uses the same eZScript underneath, so knowing it helps either way.

Contents #

1. The life cycle
2. A plain script
3. The settings of eZScript::instance()
4. eZCLI output
5. Running code with the kernel: ezexec.php
6. Moving a plain script to a class

The life cycle #

Do the option parsing before initialize(), so --help answers without a database.

A plain script #

#!/usr/bin/env php
<?php
/**
 * @description Counts the items of acmereport
 */
require_once 'autoload.php';

$cli = eZCLI::instance();
$script = eZScript::instance( array( 'description' => "Counts the items of acmereport",
                                     'use-session' => false, 'use-modules' => false, 'use-extensions' => true ) );
$script->startup();
$options = $script->getOptions( '[status:]', '', array( 'status' => 'Only items with this status' ) );
$script->initialize();

$conds = $options['status'] ? array( 'status' => (string)$options['status'] ) : null;
$cli->output( 'Items: ' . eZPersistentObject::count( acmeReportItem::definition(), $conds ) );

$script->shutdown( 0 );

Run it from the installation root: php extension/acmereport/bin/php/count.php --status=open, or through the console as ext:acmereport:count.

The settings of eZScript::instance() #

eZCLI output #

Running code with the kernel: ezexec.php #

To run a PHP file once with the kernel booted (settings, extensions, database), for a diagnosis or a one-time data fix, pass it to bin/php/ezexec.php:

php bin/php/ezexec.php path/to/your-script.php
php bin/php/ezexec.php tests/bin/bootsmoke.php      # how CI boots the kernel on PHP 8.0

The file runs with the kernel's classes and settings available; eZDB::instance() connects to the site's database. Keep such files out of the web root's reach and out of your extension's releases, and give them a name that says what they do. Anything you run twice belongs in a proper command.

Moving a plain script to a class #

1. Create extension/<ext>/classes/runnable/commands/<name>.php with a class extending Exponential\Runnable\Command in Exponential\Command\Extension\<Ext>.
2. Move the code into run(); replace eZScript::instance() with $this->script(), the three start steps with $this->startup(), $cli->output() with $this->output(), $script->shutdown() with $this->shutdown().
3. Write class names fully qualified (\eZCLI), because the class is in a namespace.
4. Reduce the old file to require_once 'autoload.php'; and one main( __FILE__ ) call.
5. Compare --help and the exit codes before and after; the kernel proved its own moves this way (Commands, cronjob parts and module views as classes).

Related pages #

• eZScript and eZCLI reference
• CLI scripts with eZScript (application creators)
• CLI scripts and console commands
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.