CLI scripts and ezexec for integrations #

This page is for integration developers whose code runs on the Exponential server: imports, exports, repairs, one-off migrations. On the command line the whole PHP API is available, there is no request timeout, and the run can be scheduled, logged and monitored. Two ways exist: bin/php/ezexec.php for a quick script, and a command of your extension for anything you keep.

Contents #

1. ezexec: a quick script with the kernel loaded
2. A command in your extension
3. Siteaccess, user and environment
4. Exit codes, dry runs and output
5. Commands that ship with Exponential and help integrations

ezexec: a quick script with the kernel loaded #

php bin/php/ezexec.php <script.php> does the bootstrap (settings, database, extensions, modules) and then includes your file. The script finds $cli (an eZCLI) and $script (an eZScript) ready to use:

<?php
// var/tmp/count_imported.php: how many objects carry our remote id prefix?
$db = eZDB::instance();
$rows = $db->arrayQuery( "SELECT COUNT(*) AS n FROM ezcontentobject WHERE remote_id LIKE 'erp-product-%'" );
$cli->output( 'Imported products: ' . (int)$rows[0]['n'] );

php bin/php/ezexec.php var/tmp/count_imported.php -s <siteaccess>

If the included file returns something other than 1 (a plain file returns 1), the exit code is 1. Use ezexec for inspection and one-off fixes; anything that runs twice belongs in your extension as a command.

A command in your extension #

The console (bin/php/console) finds scripts at run time: extension/<ext>/bin/php/<name>.php becomes the command ext:<ext>:<name>, with the one-line description taken from the @description tag of the first docblock.

#!/usr/bin/env php
<?php
/**
 * @description Import products from the ERP export file (--file, --dry-run)
 */
require_once 'autoload.php';

$cli = eZCLI::instance();
$script = eZScript::instance( array( 'description' => "Import products from the ERP export file.\n",
                                     'use-session' => false,
                                     'use-modules' => true,
                                     'use-extensions' => true ) );
$script->startup();
$options = $script->getOptions( '[file:][dry-run]', '',
                                array( 'file' => 'The export file to read',
                                       'dry-run' => 'Report what would change, change nothing' ) );
$script->initialize();

if ( !$options['file'] || !is_readable( $options['file'] ) )
{
    $cli->error( 'Give a readable --file' );
    $script->shutdown( 1 );
}

$importer = new myIntegrationProductImport( $cli, (bool)$options['dry-run'] );
$ok = $importer->run( $options['file'] );

$script->shutdown( $ok ? 0 : 1 );

Save it as extension/myintegration/bin/php/importproducts.php, make it executable, and run it:

php bin/php/console ext:myintegration:importproducts --file=var/import/products.csv --dry-run -s <siteaccess>
php extension/myintegration/bin/php/importproducts.php --help

Keep the work in a class (myIntegrationProductImport above) so the same code runs from the command, a cronjob part and a test. The body of such an importer is on Writing an import script.

Siteaccess, user and environment #

Exit codes, dry runs and output #

• Exit 0 on success and non-zero on failure, so cron, deployments and monitoring can react.
• Offer --dry-run for every script that changes data, and say what would change.
• Respect -q: $cli->output() prints nothing with it; use $cli->error() for errors, which always print.
• For long loops, show progress with $script->resetIteration( $total ) and $script->iterate( $cli, $status, $text ).
• Never print passwords, keys or personal data; mask them.

Commands that ship with Exponential and help integrations #

php bin/php/console list shows every command of the installation.

Related pages #

• CLI scripts and console commands
• eZScript and eZCLI
• Exponential Console
• Cronjobs for integrations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.