Skip to content

README.md

Latest commit

 

History

History
executable file
·
124 lines (85 loc) · 4 KB

README.md

File metadata and controls

executable file
·
124 lines (85 loc) · 4 KB

CliToolkit

Latest stable version

CliToolkit is a CLI framework for PHP scripts.

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

  • configure named (options) and positioned (arguments) parameters with ease using a builder;
  • define required options, optional arguments, lists of possible values, flags, array-like parameters and subcommands;
  • call your scripts from any paths by generated aliases (see tools/cli-toolkit/generate-autocompletion-scripts.php);
  • enjoy autocompleting options' names and parameters' possible values (when calling scripts via special aliases);
  • get a generated help page (using the built-in --help option) based on your parameters configuration.

Contents

Installation

The only requirement is PHP >= 8.1

Use composer:

composer require magic-push/cli-toolkit

... or just clone / download this repository.

How to

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 the --help option:

$ 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();
$ my-cool-script.php
'chunk-size' >>> Config error: a parameter can't be required and have a default simultaneously.

For more cool stuff to know see Features Manual.

Examples

Here are useful scripts that also utilize some Parametizer features (so may be studied as examples).

  • generate-autocompletion-scripts.php You should start with this script, as it enables the autocompletion for all Parametizer-powered scripts.
    • Launch the script and show the details: php tools/cli-toolkit/generate-autocompletion-scripts.php --verbose
    • Read it's manual for further customization: php tools/cli-toolkit/generate-autocompletion-scripts.php --help
  • terminal-formatter-showcase.php This script shows examples and codes for a terminal coloring and formatting by utilizing the TerminalFormatter class included in the project.

You can also read the Tests/*/scripts/ directories as artificial examples.

Inspiration and authors

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.

The Question class was developed by Vasiliy Borodin.

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

More info