CliArgs v3.0.0 for PHP >= 5.5

About

Class CliArgs helps to get options from the command line argument list easy.

Features

• CliArgs uses $GLOBAL['argv'] as base, and it does not use function getopt().
• It does not implement logic for 'required', it should be in your side.
• It helps to get options easy from command line argument list.
• It generates help info about options based on config.
• Flexible configuration and data filtering.

Note

This class is not workable when register_argc_argv is disabled.

Usage

Example

run

> example.php --name=Alexander --age=32 --sex=m
or
> example.php -n Alexander -a 32 -s m

example.php

$config = [
    'name' => 'n',
    'age' => 'a',
    'sex' => 's'
];
$CliArgs = new CliArgs($config);

echo $CliArgs->getArg('name'); // Alexander
echo $CliArgs->getArg('n'); // Alexander

echo $CliArgs->getArg('age'); // 42
echo $CliArgs->getArg('a'); // 42

echo $CliArgs->getArg('sex'); // m
echo $CliArgs->getArg('s'); // m

Config

Note: all params from cli that you want to use should be specified in config, otherwise they will be ignored.

$config = [
    // You should specify key as name of option from the command line argument list.
    // Example, name <param-name> for --param-name option
    'param-name' => [

        'alias' => 'p',
            // [optional], [string]
            // Alias helps to have short or long name for this key.
            // Example, name <p> for -p option

        'default' => false,
            // [optional], [mixed], [default = null]
            // Default value will returned if param is not setted
            // or params has not value.

        'help' => 'Some description about param',
            // [optional], [string]
            // Text that will returned, if you request help

        'filter' => 'int',
            // [optional], [string | array | callable]
            // Filter for the return value.
            // You can use next filters: flag, bool, int, float, help, json, <array>, <function>

            // 'int' - cast to integer before return.
            // 'float' - cast to float before return.
            // 'bool' - cast to bool before return. Yes, true, 1 = TRUE, other = FALSE
            // 'json' - decode JSON data before return.
            // 'flag' - will return TRUE, if key is exists in command line argument list, otherwise - FALSE
            // <array> - use array for enums. Example use ['a', 'b', 'c'] to get only one of these.
            // <callable> - use function($value, $default) { ... } to process value by yourself
    ]
];

$CliArgs = new CliArgs($config);

Examples of config:

Example 1

// Simple configs

// The config1 and config2 are equal
$config1 = ['foo', 'bar', 'a'];
$config2 = [
    'foo' => [],
    'bar' => [],
    'a' => [],
];

// The config3 and config4 are equal
$config3 = ['foo' => 'f', 'bar' => 'b', 'a'];
$config4 = [
    'foo' => [
        'alias' => 'f',
    ],
    'bar' => [
        'alias' => 'b',
    ],
    'a' => [],
];

Example 2

$config = [
    'help' => [
        'alias' => 'h',
        'help' => 'Show help about all options',
    ],
    'data' => [
        'alias' => 'd',
        'filter' => 'json',
        'help' => 'Some description about this param',
    ],
    'user-id' => [
        'alias' => 'u',
        'filter' => 'int',
        'help' => 'Some description about this param',
    ]
];
$CliArgs = new CliArgs($config);

Show help
> some-script.php --help
<?php if ($CliArgs->isFlagExist('help', 'h')) echo $CliArgs->getHelp('help'); ?>

Show help only for param data
> some-script.php --help data
<?php if ($CliArgs->isFlagExist('help')) echo $CliArgs->getHelp('help'); ?>

Show help for all params data
> some-script.php --help data
<?php if ($CliArgs->isFlagExist('help')) echo $CliArgs->getHelp(); ?>

All the same:
> some-script.php --data='{"foo":"bar"}' --user-id=42
or
> some-script.php --data '{"foo":"bar"}' --user-id 42
or
> some-script.php -d '{"foo":"bar"}' --user-id 42
or
> some-script.php -d '{"foo":"bar"}' -u 42

<?php
    print_r($CliArgs->getArg('data'));
    print_r($CliArgs->getArg('d'));
    print_r($CliArgs->getArg('user-id'));
    print_r($CliArgs->getArg('u'));

Example 3

    $config = [
        'flag' => [
            'alias' => 'f',
            'filter' => 'flag',
        ],
        'id' => [
            'filter' => 'int',
        ],
        'any' => [],
    ];

> some-script.php --flag

> some-script.php -f

> some-script.php -f --id=42 --any="any value"

> some-script.php --any="any value"

<?php
    print_r($CliArgs->isFlagExist('flag')); // or $CliArgs->isFlagExist('f')
    print_r($CliArgs->getArg('data'));
    print_r($CliArgs->getArg('d'));
    print_r($CliArgs->getArg('user-id'));
    print_r($CliArgs->getArg('u'));

Example 4

    $config = [
        'name' => [
            'alias' => 'n',
            'filter' => function($name, $default) {
                return $name ? mb_convert_case($name, MB_CASE_TITLE, 'UTF-8') : $defult;
            },
            'default' => 'No name',
        ],
        'sex' => [
            'alias' => 's',
            'filter' => ['m', 'f'],
            'default' => null,
        ],
        'city' => [
            'alias' => 'c',
            'filter' => function($city) {
                // ... some checks of city
            },
        ],
        'email' => [
            'alias' => 'e',
            'filter' => function($city) {
                // ... some checks of email
            },
        ]
    ];

> some-script.php --name alexander

> some-script.php -f

> some-script.php -f --id=42 --any="any value"

> some-script.php --any="any value"

<?php
    print_r($CliArgs->getArg('name'));
    print_r($CliArgs->('d'));
    print_r($CliArgs->getArg('user-id'));
    print_r($CliArgs->getArg('u'));

Create a new instance

// simple config
$config = ['foo' => 'f', 'bar' => 'b'];
$CliArgs = new CliArgs($config);

Methods

> example.php --foo Hello --bar World

new CliArgs(array|null $config = null)

Constructor. If config contents wrong aliases then ConfigErrorException will be thrown.

$config = ['foo' => 'f', 'bar' => 'b'];
$CliArgs = new CliArgs($config);

getArgs(): array

The method returns all passed arguments which is specified in config.

$argv = $CliArgs->getArgs();
print_r($argv);
// array(
//    'foo' => 'Hello',
//    'bar' => 'World',
// )

getArg(string $key): mixed | null

Returns value for argument by key. If argument is not set, then it will return default value or null

$arg = $CliArgs->getArg('foo');
// or $CliArgs->getArg('f');
echo $arg; // Hello

isFlagExist(string $key, boolean $checkAlias = true): bool

Return true if key exists, otherwise the method returns false If $checkAlias is true, then the method will check key and alias, and will return true if key or alias exists. If $checkAlias is false, then the method will check only key and will return true only if key exists.

// some_script.php --foo

$CliArgs = new $CliArgs(['foo' => 'f']);

echo $CliArgs->isFlagExist('foo'); // true
echo $CliArgs->isFlagExist('f'); // true

echo $CliArgs->isFlagExist('foo', false); // true
echo $CliArgs->isFlagExist('f', false); // false

getArguments(): array

Get prepared arguments from ARGV

print_r($CliArgs->getArguments());
// array(
//     0 => 'example.php'
//    'foo' => 'Hello',
//    'bar' => 'World',
// )

geHelp([string $value = null]): string

Get help

echo $CliArgs->getHelp(); //  Get help for all params
echo $CliArgs->getHelp('help'); //  Get help for secified params: --help data

Installation

Composer

Download composer:

wget -nc http://getcomposer.org/composer.phar

and add dependency to your project:

php composer.phar require cheprasov/php-cli-args

Running tests

./vendor/bin/phpunit

Something doesn't work

Feel free to fork project, fix bugs and finally request for pull (do not forget write tests please)