magic-push/cli-toolkit

CLI framework for PHP

Maintainers

Details

github.com/MagicPush/cli-toolkit

Source

Issues

Installs: 19

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

Type:project

v2.1.0 2025-04-06 15:20 UTC

Requires

MIT 251753af418d4871fd75f99d2e140ac6aad9dac7

This package is auto-updated.

Last update: 2025-07-25 10:35:11 UTC

README

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