Utility classes to write PHP command-line scripts

v1.4.5 2017-11-15 21:10 UTC


Utility classes to write PHP command-line scripts

Build Status Code Climate Test Coverage Dependency Status

Latest Stable Version PHP version License


php-cli-helpers is available through Composer.

  "require": {
    "amercier/cli-helpers": "1.*"
php composer.phar install

If you are not familiar with Composer, please read the full installation intructions.



Utility class to handle command-line parameters.

$options = \Cli\Helpers\Parameter::getFromCommandLine(array(
    'host'     => new Parameter('h', 'host'    , ''),
    'username' => new Parameter('u', 'username', Parameter::VALUE_REQUIRED),
    'password' => new Parameter('p', 'password', Parameter::VALUE_REQUIRED),
    'verbose'  => new Parameter('v', 'verbose' , Parameter::VALUE_NO_VALUE),

$options['host'];     // given -h/--host, or otherwise
$options['username']; // given -u/--username
$options['password']; // given -p/--password
$options['verbose'];  // true if -v/--verbose is given, false otherwise

See API Documentation for Parameter

\Cli\Helpers\Script and \Cli\Helpers\DocumentedScript

Utility class to write scripts as objects.

#!/usr/bin/env php
require_once dirname(__FILE__) . '/path/to/vendor/autoload.php';

use Cli\Helpers\DocumentedScript;
use Cli\Helpers\Parameter;

$script = new DocumentedScript();
    ->setDescription('Test script for Cli\Helpers\DocumentedScript')
    ->setCopyright('Copyright (c) Alexandre Mercier 2014')
    ->addParameter(new Parameter('H', 'host'    , '')              , 'Host.')
    ->addParameter(new Parameter('u', 'username', Parameter::VALUE_REQUIRED), 'User name.')
    ->addParameter(new Parameter('p', 'password', Parameter::VALUE_REQUIRED), 'Password.')
    ->addParameter(new Parameter('v', 'verbose' , Parameter::VALUE_NO_VALUE), 'Enable verbosity.')
    ->setProgram(function ($options, $arguments) {

While Script doesn't have any pre-configured switch, DocumentedScript has --h, --help and -V, --version. This provides an automatic handling of this two switches.

Version example:

test-documented-script.php -V

test-documented-script.php v1.0
Copyright (c) 2014 Alexandre Mercier

Help example:

test-documented-script.php -h

Usage: test-documented-script.php -p PASSWORD -u USERNAME [OPTIONS]

Test script for Cli\Helpers\DocumentedScript

  -H, --host     HOST        Host (defaults to '').
  -u, --username USERNAME    User name.
  -p, --password PASSWORD    Password.
  -v, --verbose              Enable verbosity.
  -h, --help                 Display this help and exit.
  -V, --version              Output version information and exit.

test-documented-script.php v1.0
Copyright (c) 2014 Alexandre Mercier


Utility class to run a job and catch exceptions.

On successful jobs:

\Cli\Helpers\Job::run('Doing awesome stuff', function() {
    ... // awesome stuff
Doing awesome stuff... OK

On unsuccessful jobs:

\Cli\Helpers\Job::run('Fighting Chuck Norris', function() {
    ... // throws a RoundHouseKickException('You've received a round-house kick', 'face')
Fighting Chuck Norris... NOK - You've received a round-house kick in the face

You can also add parameters to the function:

    'Doing awesome stuff',
    function($a, $b) {
        $a; // => 1337;
        $b; // => 'good luck, im behind 7 firewalls';
    array(1337, 'im behind 7 firewalls')

See API Documentation for Job


Utility class to handle standard input/output.



\Cli\Helpers\IO::form('an apple', array(
    'Golden Delicious',
    'Granny Smith',
    'Pink Lady',
    'Royal Gala',

will display:

1. Golden Delicious
2. Granny Smith
3. Pink Lady
4. Royal Gala

Choose an apple: |

Then, user is asked to make a choice between 1 and 3 on standard input.


echo IO::strPadAll(
    array( // items
        array('#', 'EN', 'FR', 'ES'),
        array('1', 'One', 'Un', 'Uno'),
        array('2', 'Two', 'Deux', 'Dos'),
        array('3', 'Three', 'Trois', 'Tres'),
        array('4', 'Four', 'Quatre', 'Cuatro'),
        array('5', 'Five', 'Cinq', 'Cinco'),
    array( // alignment
        2 => STR_PAD_LEFT,
        3 => STR_PAD_RIGHT,
    "\n", // line separator
    '   ' // field separator

will display:

#   EN          FR   ES

1   One         Un   Uno
2   Two       Deux   Dos
3   Three    Trois   Tres
4   Four    Quatre   Cuatro
5   Five      Cinq   Cinco

See API Documentation for IO


Contributions (issues ♥, pull requests ♥♥♥) are more than welcome! Feel free to clone, fork, modify, extend, etc, as long as you respect the license terms.

See contributing intructions for details.


This project is released under ISC License license. If this license does not fit your requirement for whatever reason, but you would be interested in using the work (as defined below) under another license, please contact authors.