PHP Command-Line PHP Parsing Program Arguments with getopt

PHP Command-Line PHP

Parsing Program Arguments with getopt

Problem

You want to parse program options that may be specified as short or long options, or they may be grouped.

Solution

Use the built-in getopt() function. As of PHP 5.3.0, it supports long options, optional values, and other convenient features:

       // accepts -a, -b, and -c

       $opts1 = getopt('abc');

       // accepts --alice and --bob

       $opts2 = getopt('', array('alice','bob'));

Discussion

To parse short-style options, pass getopt() the array of command-line arguments and a string specifying valid options. This example allows -a, -b, or -c as arguments, alone or in groups:

       $opts = getopt('abc');

For the previous option string abc, these are valid sets of options to pass:

       % program.php -a -b -c

       % program.php -abc

       % program.php -ab -c

The getopt() method returns an array. For each option specified on the command line, there is one element in the array. The key of the array element is the option name and the value of the array element is the option value. Counterintuitively, for flag-style options that don’t take a value (such as a, b and c in the preceding), the value in the corresponding array element is false. For example, if the preceding program is run as:

       % program.php -a -b sneeze

This makes $opts:

       array(2) {

            ["a"]=>

            bool(false)

            ["b"]=>

            bool(false)

       }

Put a colon after an option in the specification string to indicate that it requires a value. Two colons means the value is optional. So ab:c:: means that a can’t have a value, b must, and c can take a value if specified. With this specification string, running the program as:

       % program.php -a -b sneeze

This makes $opts:

       array(2) {

            ["a"]=>

            bool(false)

            ["b"]=>

            string(6) "sneeze"

       }

Instead of being ignored as an unspecified option, sneeze is now set as the value of b.

To parse long-style arguments, supply a second argument to getopt() containing an array that describes your desired arguments. Put each argument in an array element (leave off the leading --) and follow it with : to indicate a mandatory argument or :: to indicate an optional argument. The first argument to getopt() (the string for shortstyle arguments) can be left blank or not, depending on whether you also want to parse short-style arguments. This example allows debug as an argument with no value, name with a mandatory value, and size with an optional value:

       $opts = getopt('',array('debug','name:','size::'));

These are valid ways to run this program:

       % program.php --debug

       % program.php --name=Susannah

       % program.php --name Susannah

       % program.php --debug --size

       % program.php --size=56 --name=Susannah

       % program.php --name --debug

The last example is valid (if counterproductive) because it treats --debug as the value of the name argument and doesn’t consider the debug argument to be set. Values can be separated from their arguments on the command line by either an = or a space.

Note that for long-style arguments, getopt() does not include the leading -- in the array of parsed arguments. An argument specified as --name on the command line results in a key of name in the parsed argument array.