eZScript and eZCLI
Part 8, reference 14. eZScript (kernel/classes/ezscript.php) sets up the kernel for a command line script;
eZCLI (lib/ezutils/classes/ezcli.php) writes to the terminal. A complete script and the console's way of finding
it are in CLI scripts and console commands.
eZScript
| Method | Use |
|---|---|
eZScript::instance( $settings = array() ) (static) | the script object |
startup() | basic initialization; call first |
getOptions( $config = '', $argumentConfig = '', $optionHelp = false, ... ) | parse options and arguments; handles --help |
initialize() | siteaccess, database, extensions; call after getOptions() |
isQuiet() | whether -q was given |
resetIteration( $iterationMax = false, $startIndex = 0 ), iterate( $cli, $status, $text = false ) | a progress display for loops |
setUseDebugOutput( $useDebug ) | debug output at the end |
shutdown( $exitCode = false, $exitText = false ) | clean exit with an exit code |
instance() settings used most:
| Key | Meaning |
|---|---|
description | the text --help shows |
use-session | start a session (rarely needed) |
use-modules | load the module system |
use-extensions | read active extensions' settings (almost always true) |
getOptions() option syntax: [name:] takes a value (--name=Ada), [flag] does not, [n:] is a short option.
The return value is an array keyed by option name, plus arguments for the positional arguments.
A loop with progress
$cli = eZCLI::instance();
$script = eZScript::instance( array( 'description' => "Re-index items.\n", 'use-extensions' => true ) );
$script->startup();
$options = $script->getOptions( '[limit:]', '', array( 'limit' => 'How many items (default: all)' ) );
$script->initialize();
$items = array( 1, 2, 3 );
$script->resetIteration( count( $items ) );
foreach ( $items as $item )
{
$ok = true; // the work for $item
$script->iterate( $cli, $ok, "Item $item" );
}
$script->shutdown( 0 );iterate() prints a . for success and a ~ for failure per item, wrapping lines with a running count.
eZCLI
| Method | Writes |
|---|---|
eZCLI::instance() (static) | the terminal object |
output( $string = false, $addEOL = true ) | normal output (suppressed with -q) |
notice( ... ), warning( ... ), error( ... ) | messages of that kind |
stylize( $styleName, $text ) | text with a style, e.g. $cli->stylize( 'success', 'Done' ) |
setUseStyles( $useStyles ) | colors on or off |
Exit codes and safety
- Exit with
0on success and non-zero on failure, so cronjobs and deployments can react. - Scripts refuse to run as root unless
--allow-root-useris given; run them as the web server's user so the files they write have the right owner. - A script that changes data should offer a dry run (
[dry-run]) and say what it would do.
Related pages
- Previous: eZModule and module results
- Next: eZFile, eZDir and cluster file handlers
- Console commands for developers
- Commands, cronjob parts and module views as classes
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.