CliToolkit is a CLI-oriented library for PHP scripts.

Key features (why you would want to use it):

• create console scripts as plain php-files or classes (a classes' launcher generator is provided);
• configure named (options) and positioned (arguments) parameters with ease using a config builder;
• define required options, optional arguments, lists of possible values, flags, array-like parameters and subcommands;
• enjoy Bash completion for options' names and parameters' possible values, when calling scripts via generated aliases; additionally, call your scripts from any path by those generated aliases;
• see generated help pages (using the built-in --help option) for your scripts based on your parameters configuration;
• zero dependencies (apart from PHP itself).

• Installation
• How to
  • Plain scripts
  • Completion
  • Script classes
  • More configuration examples
• CliToolkit values
• Inspiration and authors
• More info

composer require magic-push/cli-toolkit

Just create a php-file and start configuring:

// Configure your script parameters
$request = Parametizer::newConfig()
    ->newArgument('chunk-size') // A positioned parameter.
    ->newFlag('--dry-run') // A named boolean parameter.

    ->run();

// Read parameters
$chunkSize = $request->getParamAsInt('chunk-size');

// Process...

if (!$request->getParamAsBool('dry-run')) {
    // Make data changes.
}

If you want to read your script's documentation, then just call your script with --help option:

$ php path/to/my-cool-script.php --help

USAGE

  my-cool-script.php [--dry-run] <chunk-size>

OPTIONS

  --dry-run

  --help      Show full help page.

ARGUMENTS

  <chunk-size>
  (required)

Config and parameter builders will guide you with available options you can set up. If you set something odd, then built-in validators will show you corresponding errors:

$request = Parametizer::newConfig()
    ->newArgument('chunk-size')
    ->default(100)
    ->required()

    ->run();

$ php my-cool-script.php
'chunk-size' >>> Config error: a parameter can't be required and have a default value simultaneously.

Generate a skeleton for your future class-based scripts:

php tools/cli-toolkit/run.php cli-toolkit:generate:launcher-skeleton

Read the output and comments in generated files.

The generated files will include completion script local/completion.sh and its generator script generate-completion.sh for your convenience, so you may skip the next section about completion.

Generate a completion Bash script with aliases to your Parametizer-based scripts:

• (as an example) Enable completion for the library stock launcher. Execute the command below and read the output:

  php tools/cli-toolkit/run.php cli-toolkit:generate:completion-script \
      --search-directory-recursive=tools/cli-toolkit \
      --verbose

• Read the script's help page for parameter details and customize the command to detect your scripts:

  php tools/cli-toolkit/run.php cli-toolkit:generate:completion-script --help

Check out the stock class scripts (see setUpConfig()) as examples of class-based scripts, and /**/scripts/* files in Tests subdirectories as artificial examples of plain scripts.

This library is being developed while keeping in mind these values:

• Scripts' development and maintenance should be quick and simple. The library users may focus on their scripts' unique logic instead of parameters or infrastructure management. The library builders and generators cover the latter.

• No dependencies apart from PHP and its standard modules. Updating the library should be a simple task: no dependencies - no extra libraries to worry about.

  The only tough part here is moving to the next major version.

CliToolkit was inspired by and based on Cliff project, so the first author is Aleksandr Galkin.

A part of ideas and code for CliToolkit v1.0.0 was brought by Anton Kotik.

Question class was developed by Vasiliy Borodin.

The rest is done by Kirill "Magic Push" Ulanovskii.

• Features Manual - more cool stuff to know about in details.
• TODO - the list of things I think would be cool to implement in the library.
• Changelog - if you want to update the library safely.