Manual

Console_Getopt provides functions for easily fetching and processing command-line arguments.

Introduction - Options

Introduction - Options – Defining and processing options

Defining options

Getopt() supports two types of options: short options and long options

Calling a script with short and long options

# Using short options

myphpscript -q -l en -o

# Using long options instead

myphpscript --quite --lang=en --option

# Mixing both

myphpscript -q --lang=en -o

You have to define which options you want to support. The second argument of getopt() requires a string containing all supported chars. For the example above this would be at least:

<?php
$shortoptions = "qlo";
?>

The order of the characters is not important. Often you have to define options with (optional) parameters. To express that a option requires a parameter, you have to add a colon. If the parameter is optional, add a double colon, ie:

<?php
$shortoptions = "ql:o::";
?>

this means the following script calls are permitted, ie.

myphpscript myphpscript -q myphpscript -q -l en myphpscript -o text myphpscript -o

whilst

myphpscript -l

is not permitted. The -l option requires a parameter, if the option is used.

The long options work equally, but they have to be defined in an array:

<?php
$longoptions = array("quite", "lang", "option");
?>

For defining optional parameters, use '=' and '==' like the colon in short options.

<?php
$longoptions = array("quite", "lang=", "option==");
?>

The returned options array

The return value is an array of two elements: the list of parsed options and the list of non-option command-line arguments. Each entry in the list of parsed options is a pair of elements - the first one specifies the option, and the second one specifies the option argument, if there was one, else the value is NULL.

Console_Getopt::getopt

Console_Getopt::getopt – fetch the command-line options

Synopsis

require_once 'Console/Getopt.php';

array getopt ( array $args , string $shortoptions , array $longoptions = null )

Description

Parses the command-line options and returns them.

Parameter

array $args - an array of command-line arguments
string $shortoptions - specifies the list of allowed short options. See the "Options" section for more information.
array $longoptions - specifies the list of allowed long options. Default is NULL. See the "Options" section for more information.

Return value

array - two-element array containing the list of parsed options and the non-option arguments or a PEAR_Error.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"Console_Getopt: option --`$opt` is ambiguous"	Two or more long options starts with the same character.	Change the naming of the options. It is also possible that the error is caused by a typing mistake.
NULL	"Console_Getopt: option --`$opt` requires an argument"	No parameter for a option was given.	Normally this is a user mistake. If the parameter is optional, you have to markup the parameter as optional in the option definitions.
NULL	"Console_Getopt: option --`$opt` doesn't allow an argument"	A parameter for a option was given.	Normally this is a user mistake. If the option requires a (optional) parameter, you have to markup it in the options definition.
NULL	"Console_Getopt: unrecognized option --`$opt`"	Unknown option.	Normally this is a user mistake. If the option exists, you have to define them in the options definition.

Note

This function can not be called statically.

Console_Getopt::readPHPArgv

Console_Getopt::readPHPArgv – read the predefined $argv array

Synopsis

require_once 'Console/Getopt.php';

array readPHPArgv ( )

Description

Reads the $argv PHP array across different PHP configurations. Will take care of the register_globals and register_argc_argv ini directives.

Return value

array - array containing the options and parameters or PEAR_Error

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"Console_Getopt: Could not read cmd args (register_argc_argv=Off?)"	PHP does not provide the command-line arguments for the script.	Check "register_argc_argv" in your php.ini

Note

This function can not be called statically.

Example

Using readPHPArgv()

<?php
$con  = new Console_Getopt;
$args = $con->readPHPArgv();
array_shift($args);
$options = $con->getopt2($args, $shortopt);
?>

Examples

The following example shows how to setup short and long option arrays as well as reading the arguments passed via commandline. The example also introduces a helper method that converts the parsed parameters returned by Console_Getopt into a key-value-array.

<?php
/**
 * Example how to get a key-value pair array
 * from command line parameters with Console_Getopt.
 *
 * @link http://pear.php.net/bugs/bug.php?id=13902
 */
require_once 'Console/Getopt.php';

/**
 * Make a key-value array.
 * Since Console_Getopt does not provide such a method,
 * we implement it ourselves.
 *
 * @params array $params Array of parameters from Console_Getopt::getopt2()
 *
 * @return array key-value pair array
 */
function &condense_arguments($params)
{
    $new_params = array();
    foreach ($params[0] as $param) {
        $new_params[$param[0]] = $param[1];
    }
    return $new_params;
}


$cg = new Console_Getopt();
$args = $cg->readPHPArgv();
array_shift($args);

$shortOpts = 'u:g:';
$longOpts  = array('user=', 'group=');

$params = $cg->getopt2($args, $shortOpts, $longOpts);
if (PEAR::isError($params)) {
    echo 'Error: ' . $params->getMessage() . "\n";
    exit(1);
}

var_dump(condense_arguments($params));
/*
When called as follows:
 associative.php -u jason -g argonauts
you will get this output:
 array(2) {
   ["u"]=>
   string(5) "jason"
   ["g"]=>
   string(9) "argonauts"
 }
 */
?>