Command line: the console and eZScript #

This page is for developers who live in bin/console, php artisan, manage.py or bin/rails. Exponential has one entry point for every command, bin/php/console (installations usually add a ./console shortcut in the root). It finds commands at run time from their file location, so an extension's command needs no registration (Exponential Console, Console commands).

Contents #

1. Finding commands
2. Command names
3. Writing a command
4. Siteaccess, user and root
5. Commands you will use daily
6. Compared with other frameworks

Finding commands #

php bin/php/console                   # every command
php bin/php/console list ext:expdemo  # one namespace
php bin/php/console --version

Command names #

A script can declare extra names with an @alias tag in its docblock (bin/php/exphelp.php declares @alias exp:help), and a @description tag describes it in list.

Writing a command #

New commands are classes extending Exponential\Runnable\Command, called by a one-line script (CLI scripts with eZScript):

<?php
// extension/expdemo/classes/runnable/commands/report.php
namespace Exponential\Command\Extension\Expdemo;

class Report extends \Exponential\Runnable\Command
{
    public function run()
    {
        $this->script( array( 'description' => "Writes the monthly report",
                              'use-session' => false, 'use-modules' => true, 'use-extensions' => true ) );
        $options = $this->startup( '[month:][dry-run]', '', array(
            'month'   => 'The month, YYYY-MM',
            'dry-run' => 'Show what would be written, write nothing' ) );
        $this->output( \expDemoReportService::build( $options['month'], !empty( $options['dry-run'] ) ) );
        $this->shutdown( 0 );
    }
}

#!/usr/bin/env php
<?php
// extension/expdemo/bin/php/report.php
require_once 'autoload.php';
\Exponential\Command\Extension\Expdemo\Report::main( __FILE__ );

Run it: php bin/php/console ext:expdemo:report --month=2026-10 --dry-run. The classic form, used by many scripts, calls eZScript::instance(), startup(), getOptions(), initialize() and shutdown() directly; output goes through eZCLI (output(), notice(), warning(), error()). Option strings use [name:] for a value and [name] for a flag; --help, -s/--siteaccess, --allow-root-user and the debug options are added for you.

Siteaccess, user and root #

• -s <siteaccess> selects the settings; extensions active only in that siteaccess need it.
• The user is anonymous. A command that writes content signs in a dedicated user (eZUser::setCurrentlyLoggedInUser( $user, $user->id() )), never the shared administrator.
• Scripts refuse to run as root unless --allow-root-user is given; run them as the web server's user, because files a root process writes into var/ break the site later.
• The exit code is returned unchanged: shutdown( 0 ) for success, anything else for failure.
• Offer --dry-run for every command that writes or deletes, and never accept passwords as options.

Commands you will use daily #

Compared with other frameworks #

Related pages #

• Commands, cronjob parts and module views as classes
• Command pattern
• Scheduled tasks: cronjobs
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.