Documentation

ALeX Kazik edited this page Jul 3, 2016 · 2 revisions
Clone this wiki locally

GetOpts

GetOpts - a replacement for php's getopt — easier to handle, also returns the other arguments and more.

License: Creative Commons Attribution 3.0 Unported License http://creativecommons.org/licenses/by/3.0/

Requirement

PHP 5.4+

Usage

(new GetOpts($params))->parse($args=null)

  • $params: is a list of options to parse.

    • key: user defined parameter name
    • value: type und name(s) of options (see Parameters)
  • $args: are the arguments to parse. if not set, they default to the arguments passed to php.

Returns

list($errors, $params, $args) = ...->parse(...)

In case of an problem while parsing the parameters or when not an array of strings is passed as arguments an exception is thrown.

  • $errors: is either false if there is no error otherwise it's an array of strings describing the errors. (usually you'll print the first and exit in case of an error, see Example) (the other errors may be subsequent errors)

  • $params: is an array of all parameters

    • key: user defined parameter name (as defined in the parameter)
    • value: bool, int, string or array of string/bool, dependent of the type
  • $args: is the list of all non option arguments. All arguments which are passed after a "--" will be copied directly to this array.

Example

script "test.php"

	<?php
		require_once('GetOpts.php');
		list($errors, $params, $args) = (new GetOpts([
		  'a' => [GetOpts::TOGGLE, 'a'],
		  'b' => [GetOpts::VALUE, 'b', 'long'],
		]))->parse();
		if ($errors) {
		  die($errors[0].PHP_EOL);
		}
		echo 'a = '.var_export($params['a'], true).', ';
		echo 'b = '.var_export($params['b'], true).', ';
		echo 'args = '.var_export($args, true).PHP_EOL;

sample input 1:

	php test.php -a file

output 1:

	a = true, b = false, args = array('file')

-a is given, therefore true. -b is not given. 'file' is not attached to an option and returned as args.

sample input 2:

	php test.php -a --long file -a

output 2:

	a = false, b = 'file', args = array()

-a is given twice, and since a is defined as toggle it's off (false). -b is given (as the long version --long). No other arguments.

Types

  • SIMPLE/TOGGLE/COUNT

    • an switch without an value
    • e.g. -s, -t, --help
    • may be combined (e.g. -ab acts like -a -b)
  • VALUE

    • an option which requires a value
    • e.g. -v=val, -vval, -v val
    • may be combined (e.g. -av3 acts like -a -v 3)
  • OPTIONAL

    • like VALUE except:
      • an value is not required (reported as true in that case)
      • the format "-o val" is not supported (use -oval, -o=val, -o)
  • ASSOCIATIVE

    • an option which requires a key and a value
    • must contain a = between the key and the value
    • e.g. -akey=val, -a key=val, -a=key=val

Subtypes

The subtype describes how it should be returned:

  • SIMPLE returns true if the option is one or multiple times is given, false otherwise

  • TOGGLE each occurrence of the option toggles it on/off returns true/false

  • COUNT counts the occurrence, returns the count (integer)

  • VALUE returns the last occurrence of the option, or false if not found

    • VALUE_MULTIPLE returns false if not found, otherwise an array of values

    • VALUE_AUTOMATIC returns false if not found, a string if only once is found, an array with all values otherwise

  • OPTIONAL like VALUE, except that the last non true value is used (if there is one which is non true)

    An option without value is returned as true. (Instead of a string, to be differentiated. Only -o= returns an empty string.)

    • OPTIONAL_MULTIPLE like VALUE_MULTIPLE

    • OPTIONAL_AUTOMATIC like VALUE_AUTOMATIC

  • ASSOCIATIVE returns an array with the keys/value pairs

Parameters

An associative array of option names and their type and names as an array.

It's an associative array, the keys are the name of the parameter, which is only used in the return value. The values are arrays with the type (e.g. GetOpts::SIMPLE) followed by the parameter name(s). (There is no limit on how many aliases an option can have.)

If the name is only a single string then it's used as a short option.

When the name is longer then it's used as a long option The long option may be preceded by an dash. If the long option is only one character long the dash must pre prepended since otherwise it would be used as a short option.

Examples of name definition and their usage:

	"a"    "-a"
	"arg"  "--arg"
	"-arg" "--arg"
	"-a"   "--a"

Get involved

Open a ticket in the issues section or create a pull request.

License

Creative Commons Attribution 3.0 Unported License