dxw / optionparser
This package is auto-updated.
Last update: 2024-04-07 14:59:49 UTC
README
Overview
OptionParser is a parser for command-line options for PHP. It supports both short and long options, optional and/or required parameter checking, automatic callback execution, and pretty printing of usage messages.
This package is a dependency of Whippet. It's been forked by dxw because the upstream repo is no longer maintained.
Usage
First create a parser object and then use it to parse your arguments. Examples explain it best:
$parser = new OptionParser; // add a rule that looks for the short "a" flag $parser->addRule('a'); // add a rule that looks for the long "long-option" flag $parser->addRule('long-option'); // add a rule that looks for the short "b" flag or long "big" flag $parser->addRule('b|big'); // to indicate an optional parameter, use a colon after the flag name $parser->addRule('c:'); // likewise, to indicate a required parameter use two colons $parser->addRule('d|debug::'); // add a description for a rule that can be used later in a usage message $parser->addRule('e', 'The description for flag e'); // or use a user-defined callback function that will be called when that // flag is used. the function will be passed the parameter that was given // to the flag, or true if the flag is optional and no parameter was used $parser->addRule('error-reporting', 'set_error_reporting');
Next, parse your arguments. This function can be called multiple times with the same parser to parse multiple sets of arguments if desired. Note: This function will throw an exception if the user has specified invalid flags. Also, if no arguments are specified here the global $argv
argument will be used.
try { $parser->parse(); } catch (Exception $e) { die("Error parsing arguments: " . $e->getMessage()); }
A more helpful error message might be to show the user the options that she can use to run your program:
$parser->addHead("Usage: myprog [ options ]\n"); try { $parser->parse(); } catch (Exception $e) { die($parser->getUsage()); }
Examples
Scripts in the examples directory may be invoked using the PHP interpreter on the command line, like so:
$ php echo.php
A Unix-style executable is also provided for *nix users:
$ ./echo
Tests
OptionParser uses the PHPUnit unit testing framework to test the code. In order to run the tests, run the following command from the project root directory:
$ vendor/bin/phpunit
Credits
OptionParser draws inspiration from several other option parsers including GNU getopt, Ruby's OptionParser, and Zend_Console_Getopt.
Requirements
OptionParser requires PHP version 5 or greater.
License
OptionParser is released under the terms of the MIT license. Please read the LICENSE file for further information.