deweller / cliopts
A no-nonsense command-line options parser and help generator for PHP CLI apps.
Installs: 18 265
Dependents: 6
Suggesters: 0
Security: 0
Stars: 15
Watchers: 4
Forks: 1
Open Issues: 0
Requires
- php: >=5.3.0
This package is not auto-updated.
Last update: 2024-10-26 13:19:15 UTC
README
A no-nonsense command-line options parser and help generator for PHP CLI apps.
Features
- Simple one-line usage with a human readable configuration format
- Parses $argv data into an associative array similar to getopt()
- Adds error validation for missing or malformed arguments or options
- Nicely formatted help generation
- Supports options (e.g. -i 100) and named arguments (./script.php /tmp/myfile.txt)
Usage
Code
In its simplest form, the parser can be used with one line of php code:
// specify the spec as human readable text $values = CLIOpts\CLIOpts::run(" {self} <in_filename> -i, --id <id> specify an id (required) -o, --out <out_filename> output filename -v be verbose -h, --help show this help "); // show the values echo "The values you supplied are:\n"; print_r((array)$values);
CLI Input
The interpretation of flags are somewhat flexible. The following lines are all handled in the same way by cliopts:
-
./script.php -v -i 101 -o /tmp/myfile.txt /tmp/infile.txt
-
./script.php -vi 101 -o /tmp/myfile.txt /tmp/infile.txt
-
./script.php -v --id 101 -o /tmp/myfile.txt /tmp/infile.txt
-
./script.php -v --id="101" -o /tmp/myfile.txt /tmp/infile.txt
All of the above will show this output:
The values you supplied are:
Array
(
[in_filename] => /tmp/infile.txt
[id] => 101
[out] => /tmp/myfile.txt
[v] =>
)
The Human Readable Text Specification
Let's look at the specification in the following bit of code:
$values = CLIOpts\CLIOpts::run(" Usage: process_files.php [options] <in_file1> [<in_file2>] -i, --id <id> specify an id (required) -v be verbose ")
The Usage Line
The spec begins with a usage line. This line is optional. But if it is provided, here is a breakdown of how the usage line is interpreted:
Usage: process_files.php [options] <in_file1> [<in_file2>]
| | | | |
| | | | + Optional second argument named in_file2.
| | | |
| | | + Required first argument named in_file1
| | |
| | + An options placeholder. This may be ommitted. It must come before any arguments.
| |
| + An optional script name. Omit this or use {self} to show $_SERVER['argv'][0].
|
+ The usage keyword. This may be ommitted.
In this example, 1 argument is expected and the value provided will be assigned to the key "in_file1" in the values object. An optional second argument will be assed to the key "in_file2" if it is provided. And that's all. If a 3rd argument is provided it will not be assigned to a value and validation will fail.
The Option Lines
Here is how the first option line is interpreted:
-i, --id <id> specify an id (required)
| | | | |
| | | | + This makes the option required when validating.
| | | |
| | | + Help text. This can be any text.
| | |
| | + This specifies that the option requires a value. Unlike arguments, this is not used for the value name.
| |
| + This is a long option name. It is not required. If specified, this is used for the value name when arguments are parsed.
|
+ This is the short option name. It is not required. Values can be accessed using this shortcut.