Download the PHP package evo/cli without Composer

Command line interface options parser

The purpose of this library is to make a more user friendly way of setting command line arguments for programs.

It's fairly strait forward so I'll jump right in with an example (will call it 'program'):

This is the form of a typical command line call, here we are assuming only that PHP is executable on calling php. For windows users you may have to add the php.exe to the system environmental variables to call PHP this way. It's not hard to do and there are plenty of tutorials on how to do this for your version of windows. Otherwise you can always call PHP using the full path to the executable on your setup.

Class refrence

Cli Class Constants

General Argument Definitions

Options (changed in 2.0.0)

OPT_VALUE_EXPECTED

When this option is true a value is expected for this argument:

• If true and the argument is set without a value prog.exe -a then it is value "false", please note this is the opposite of below
• If true and the argument is set with a value prog.exe -a=1 then it's value is set
• If false and the argument is set without a value prog.exe -a then it is value "true"
• If false and the argument is set with a value prog.exe -a=1 then it is still "true" but the value is not given

OPT_MUST_VALIDATE

This option can be either a boolean value or a Closure (or any class that impliments the Callable interface):

• If it's set to true, the argement will always validate if it's in the request
• If it's set to false, the argement will never validate if it's in the request
• If it's set to a callback, then it's the callback's responsibillity to return true or false

OPT_MULTIPLE_EXPECTED

This option deturmines if an argument can have multiple values prog.exe -a=1 -a=2 -a=3

• If it's set to true, the argements value will always be represented by an array
• If it's set to false, the argements value never be represented by an array and only the last value is set

Basic Usage

Usage is pretty simple, there are 3 main methods you will need and few others that are just nice to have.

Cli is a "Singlton" which means you can only ever have one instance of the class. Calling getInstance again will return the same instance. This is fine because we can only handle one request at any give time. The main function you will use is $Cli->setArgument (or $Cli->fromConfig()) which defines what arguments you will accept from the request.

Above we are setting up a very basic argument to show the argument help document.

The first argument is shortName, h in this case, this is mainly what you use when referring to this argument. All incoming request data will be "normalized" to use the short name. Any items in the request that do not have a corresponding argument are simply ignored. In a command line call it will be referred to as -h, for a GET or POST request it will be referred to simply as h.

The second argument is the longName, help in this case. Any incoming arguments using the optional longName will be converted to their short name equivalent. In a command line call it will be referred to as --help, for a GET or POST request it will be referred to simply as help.

The third argument is the Help Doc. This string will be compiled with all the other arguments and retuned from getHelpDoc or output from printHelpDoc. It may also be appended to InvalidArgument exceptions thrown by the libary.

The fourth argument is an array of options, currently only 2 options are supported

• 'accept' This is a callback that takes the $shortName and the [request]$value as inputs and should return true to accept the value. If false is returned the argument is removed from the request input. It is up to the developer to throw exceptions for invalid inputs. This can be easly done in the callback. The $value can be modified by reference by adding &$value (by reference).
• 'requiredValue' This is a boolen that makes a value required for the argument. If the value is not included with the argument then an evo\exception\InvalidArgument is thrown. This does not mean that the argument itself is required only that if the argument is present that an acceptable value is also included.

This is equivalent to the previous code block where each argument was provided individually. It is up to the developer to decide how this is saved. There are some limitation due to using a closure as the 'accept' option. However this could be saved in a PHP file as an array:

And then included ( or required) as follows:

The flexabillity of a callback simply outweighs difficulty in saving a config in other format.

After all your arguments are defined you can access the values they hold in the request by using $Cli->getArguments(), Like this:

Other Methods

setAllowedRequestTypes

The first other method is $Cli->setAllowedRequestTypes($requestType). This sets which type of requests are allowed and is one of the Cli::REQUEST_* bitwise constants. Currently supported values are Cli::REQUEST_CLI, Cli::REQUEST_POST and Cli::REQUEST_GET. Multiple types can be set by seperating them with a single pipe |, like a typical PHP flag. The default is Cli::REQUEST_CLI.

The Cli::R_ALL is included for allow all, this value is subject to change if additonal request types are added. Such as those for a full REST framework.

setCurrentRequestTypes This method is provided to override the autodetection. This may be nessacary in the future when implimenting things like PUT and DELETE as no all servers support these HTTP Verbs. This accepts a single Cli::REQUEST_* constant. Currently it's of limited use.

setRequest This method allows you to inject a request array such as would come from the Command line, $_GET or $_POST Supper Globals. This is mostly for testing purposes. Where you can use a canned request array to run in something like a UnitTest.

getOptions This method returns the help documents for the currently supported options. It's mainly for ease of use by Developers using this library:

getHelpDoc This method returns the help document as a string, this is compiled from the $doc args of each argument that was set. This is mainly geared towards the command line and it is up to the developer to decide how to handle this for normal HTTP requests.

printHelpDoc This is simular to the above method except that it directly outputs the help document. You can supply an optional argument to call exit (which is typical when displaying help). The default is true set to false to continue script exection. For flexabillity it is up to the developer to decide what argument is used for help, but typically it is simply h and help. An example implimentation:

Install

You can get it from composer, by requiring it.

"require" : {
    "evo/cli" : "~1.0"
}

It has 2 dependancies (which are included in the composer.json file.

"require" : {
    "evo/cli" : "~1.0"
    "evo/patterns" : "~1.0",
    "evo/exception" : "dev-master"
}

And that is pretty much it, Enjoy!