CLI scripts: Difference between revisions
David Mudrak (talk | contribs) (Add first version of the page summarising the basic info about CLI scripts) |
David Mudrak (talk | contribs) m (Text replacement - "<code php>" to "<syntaxhighlight lang="php">") |
||
(7 intermediate revisions by the same user not shown) | |||
Line 11: | Line 11: | ||
All scripts must declare themselves as CLI scripts properly by setting the <tt>CLI_SCRIPT</tt> constant before loading the main <tt>config.php</tt> file. | All scripts must declare themselves as CLI scripts properly by setting the <tt>CLI_SCRIPT</tt> constant before loading the main <tt>config.php</tt> file. | ||
< | <syntaxhighlight lang="php"> | ||
define('CLI_SCRIPT', true); | define('CLI_SCRIPT', true); | ||
require(__DIR__.'/../../../config.php'); | require(__DIR__ . '/../../../config.php'); | ||
</ | </syntaxhighlight> | ||
The path to the config.php must not use relative paths starting with <tt>../</tt>. The best practise is to avoid <tt>dirname()</tt> function call and use the <tt>__DIR__</tt> magic constant (this applies everywhere, not just for CLI scripts). | The path to the config.php must not use relative paths starting with <tt>../</tt>. The best practise is to avoid <tt>dirname()</tt> function call and use the <tt>__DIR__</tt> magic constant (this applies everywhere, not just for CLI scripts). | ||
Line 22: | Line 22: | ||
The library <tt>clilib.php</tt> provides useful functions for basic input/output operations in CLI scripts. | The library <tt>clilib.php</tt> provides useful functions for basic input/output operations in CLI scripts. | ||
< | <syntaxhighlight lang="php"> | ||
require_once($CFG->libdir.'/clilib.php'); | require_once($CFG->libdir . '/clilib.php'); | ||
</ | </syntaxhighlight> | ||
;cli_write():Write a text to the given stream, defaults to the standard output (since Moodle 3.0) | ;cli_write():Write a text to the given stream, defaults to the standard output (since Moodle 3.0) | ||
Line 35: | Line 35: | ||
;cli_error():Print message to the standard error output and exit with the given code | ;cli_error():Print message to the standard error output and exit with the given code | ||
;cli_logo():Prints ascii-graphics Moodle logo | ;cli_logo():Prints ascii-graphics Moodle logo | ||
== Script parameters == | |||
The function <tt>cli_get_params()</tt> implements a basic cross-platform parser for the script parameters. It supports long options names (with double dashes like <tt>--version</tt> or <tt>--help</tt>) by default. Some of these long options can have short name aliases (single dashed, like <tt>-v</tt> or <tt>-h</tt>). The function does not support positional arguments for CLI scripts. Input data must be provided as a value of an option: | |||
GOOD: | |||
$ php do_something_useful.php --file=/path/to/file.mbz --action=validate | |||
BAD: | |||
$ php do_something_useful.php validate /path/to/file.mbz | |||
It is a good practise that short names aliases should be used only for boolean options (flags). It is unusual in CLI environment to set values for short named options. | |||
NICE: | |||
$ php do_something_useful.php -h | |||
UGLY: | |||
$ php do_something_useful.php -f=/path/to/file.mbz | |||
For documenting the expected usage of the script, you may want to use the same format and syntax as used by [http://docopt.org/ docopt]. | |||
== Example == | |||
<syntaxhighlight lang="php"> | |||
<?php | |||
// This file is part of Moodle - https://moodle.org/ | |||
// | |||
// Moodle is free software: you can redistribute it and/or modify | |||
// it under the terms of the GNU General Public License as published by | |||
// the Free Software Foundation, either version 3 of the License, or | |||
// (at your option) any later version. | |||
// | |||
// Moodle is distributed in the hope that it will be useful, | |||
// but WITHOUT ANY WARRANTY; without even the implied warranty of | |||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |||
// GNU General Public License for more details. | |||
// | |||
// You should have received a copy of the GNU General Public License | |||
// along with Moodle. If not, see <http://www.gnu.org/licenses/>. | |||
/** | |||
* Moodle CLI script - demo.php | |||
* | |||
* @package plugintype_pluginname | |||
* @copyright 2019 Your Name <email@example.com> | |||
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |||
*/ | |||
define('CLI_SCRIPT', true); | |||
require(__DIR__ . '/../../../config.php'); | |||
require_once($CFG->libdir . '/clilib.php'); | |||
$usage = "Put a one line summary of what the script does here. | |||
Usage: | |||
# php demo.php --paramname=<value> | |||
# php demo.php [--help|-h] | |||
Options: | |||
-h --help Print this help. | |||
--paramname=<value> Describe the parameter and the meaning of its values. | |||
"; | |||
list($options, $unrecognised) = cli_get_params([ | |||
'help' => false, | |||
'paramname' => null, | |||
], [ | |||
'h' => 'help' | |||
]); | |||
if ($unrecognised) { | |||
$unrecognised = implode(PHP_EOL . ' ', $unrecognised); | |||
cli_error(get_string('cliunknowoption', 'core_admin', $unrecognised)); | |||
} | |||
if ($options['help']) { | |||
cli_writeln($usage); | |||
exit(2); | |||
} | |||
if (empty($options['paramname'])) { | |||
cli_error('Missing mandatory argument paramname.', 2); | |||
} | |||
// Do something useful here. | |||
</syntaxhighlight> |
Latest revision as of 13:38, 14 July 2021
CLI (command line interface) scripts can be executed from the command line (terminal) only.
Location
It is a convention in the Moodle code that all CLI scripts are put into the cli/ folder inside the component/plugin directory.
Examples: admin/cli/, enrol/ldap/cli/, admin/tool/task/cli/ and others
CLI_SCRIPT constant
All scripts must declare themselves as CLI scripts properly by setting the CLI_SCRIPT constant before loading the main config.php file.
define('CLI_SCRIPT', true);
require(__DIR__ . '/../../../config.php');
The path to the config.php must not use relative paths starting with ../. The best practise is to avoid dirname() function call and use the __DIR__ magic constant (this applies everywhere, not just for CLI scripts).
clilib.php
The library clilib.php provides useful functions for basic input/output operations in CLI scripts.
require_once($CFG->libdir . '/clilib.php');
- cli_write()
- Write a text to the given stream, defaults to the standard output (since Moodle 3.0)
- cli_writeln()
- Write a text followed by an end of line symbol to the given stream (since Moodle 3.0)
- cli_input()
- Prompt the user for an input value
- cli_get_params()
- Parse and return arguments passed to the script
- cli_separator()
- Print or return section separator string
- cli_heading()
- Print or return section heading string
- cli_problem()
- Print error notification
- cli_error()
- Print message to the standard error output and exit with the given code
- cli_logo()
- Prints ascii-graphics Moodle logo
Script parameters
The function cli_get_params() implements a basic cross-platform parser for the script parameters. It supports long options names (with double dashes like --version or --help) by default. Some of these long options can have short name aliases (single dashed, like -v or -h). The function does not support positional arguments for CLI scripts. Input data must be provided as a value of an option:
GOOD:
$ php do_something_useful.php --file=/path/to/file.mbz --action=validate
BAD:
$ php do_something_useful.php validate /path/to/file.mbz
It is a good practise that short names aliases should be used only for boolean options (flags). It is unusual in CLI environment to set values for short named options.
NICE:
$ php do_something_useful.php -h
UGLY:
$ php do_something_useful.php -f=/path/to/file.mbz
For documenting the expected usage of the script, you may want to use the same format and syntax as used by docopt.
Example
<?php
// This file is part of Moodle - https://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Moodle CLI script - demo.php
*
* @package plugintype_pluginname
* @copyright 2019 Your Name <email@example.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
define('CLI_SCRIPT', true);
require(__DIR__ . '/../../../config.php');
require_once($CFG->libdir . '/clilib.php');
$usage = "Put a one line summary of what the script does here.
Usage:
# php demo.php --paramname=<value>
# php demo.php [--help|-h]
Options:
-h --help Print this help.
--paramname=<value> Describe the parameter and the meaning of its values.
";
list($options, $unrecognised) = cli_get_params([
'help' => false,
'paramname' => null,
], [
'h' => 'help'
]);
if ($unrecognised) {
$unrecognised = implode(PHP_EOL . ' ', $unrecognised);
cli_error(get_string('cliunknowoption', 'core_admin', $unrecognised));
}
if ($options['help']) {
cli_writeln($usage);
exit(2);
}
if (empty($options['paramname'])) {
cli_error('Missing mandatory argument paramname.', 2);
}
// Do something useful here.