README

Utility classes to write PHP command-line scripts

Installation

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.

Usage

\Cli\Helpers\Parameter

Utility class to handle command-line parameters.

$options = \Cli\Helpers\Parameter::getFromCommandLine(array(
    'host'     => new Parameter('h', 'host'    , '127.0.0.1'),
    '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 127.0.0.1 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
<?php
require_once dirname(__FILE__) . '/path/to/vendor/autoload.php';

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

$script = new DocumentedScript();
$script
    ->setName('test-documented-script.php')
    ->setVersion('1.0')
    ->setDescription('Test script for Cli\Helpers\DocumentedScript')
    ->setCopyright('Copyright (c) Alexandre Mercier 2014')
    ->addParameter(new Parameter('H', 'host'    , '127.0.0.1')              , '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) {
        var_dump($arguments);
        var_dump($options);
    })
    ->start();

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 '127.0.0.1').
  -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

\Cli\Helpers\Job

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:

\Cli\Helpers\Job::run(
    '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

\Cli\Helpers\IO

Utility class to handle standard input/output.

IO::form

Usage

\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.

IO::strPadAll

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

Contributing

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.

Licensing

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.