CLI Parser

This project is build around a slightly modified version of this fairly old comment on php.net.

This is for you, if...

...you are creating CLI applications with PHP, that take some command line arguments, options, commands and/or flags.

Install

Note: This library requires PHP 8.0+!

Use composer to install this library:

composer require nerou/cli-parser

There are no dependencies.

Usage

Wording

Command is just some value, e.g. myscript.php hello

Option starts with -- and can have a value, e.g. myscript.php --foo or myscript.php --foo=bar or myscript.php --foo bar

Flag starts with - and is a short form of an option, e.g. myscript.php -f or myscript.php -f bar

Argument is everything following a standalone --

Validation

You can use PHP's Filter Extension to validate provided option values (see examples below). There is a strict mode which can be enabled to abort parsing if there is an option provided for which the validation fails. Otherwise, this specific option is ignored. Either way, an error will be present when calling getErrors().

When you want to add arrays to your CLI by allowing a single option to be used multiple times, note the following validation behavior:

• The FILTER_REQUEST_SCALAR flag does not allow multiple values for a single option, meaning only the last value is parsed.
• The FILTER_FORCE_ARRAY flag works as documented on php.net, meaning even if an option is provided only once, the value will be wrapped in an array.
• The FILTER_REQUIRE_ARRAY flag is basically ignored.

Examples

Minimal example with options --foo and --bar as well as the flag -f which is a short form of --foo:

if(PHP_SAPI !== 'cli' || !isset($_SERVER['argv'])){
  exit(1);          // exit if not run via CLI
}

$cliArgs = new CLIParser($_SERVER['argv'], '[--foo] [--bar]');
$cliArgs->setAllowedOptions(['foo', 'bar']);    // list of supported options
$cliArgs->setAllowedFlags(['f' => 'foo']);      // maps flags to options
$cliArgs->setStrictMode(true);                  // parse() will return `false` if there are options/flags that are not allowed
if(!$cliArgs->parse()){
  $cliArgs->printUsage();     // show them how to use this script
  exit(1);
}

Use value validation (see PHP filters):

$cliArgs->setAllowedOptions([
    'foo' => [
        'filter' => FILTER_VALIDATE_FLOAT,
        'flags' => FILTER_FLAG_ALLOW_THOUSAND,
        'options' => [
            'min_range' => 0,
            'default' => 42                   // default value which will also be added to usage documentation
        ],
        'value_label' => 'my-val',            // for usage documentation
        'description' => 'pass some float'    // for usage documentation
    ], 
    'bar' => []     // defaults to `['filter' => FILTER_DEFAULT]`
]);

License

This library is licensed under the MIT License. Please see LICENSE for more information.