Zeta Components - high quality PHP components

This class allows the complete handling of options and arguments submitted to a console based application.

The next example demonstrate how to capture the console options:

1.  $optionHandler = new ezcConsoleInput();
2.  
3.  // Register simple parameter -h/--help
4.  $optionHandler->registerOption( new ezcConsoleOption( 'h', 'help' ) );
5.  
6.  // Register complex parameter -f/--file
7.  $file = new ezcConsoleOption(
8.   'f',
9.   'file',
10.   ezcConsoleInput::TYPE_STRING,
11.   null,
12.   false,
13.   'Process a file.',
14.   'Processes a single file.'
15.  );
16.  $optionHandler->registerOption( $file );
17.  
18.  // Manipulate parameter -f/--file after registration
19.  $file->multiple = true;
20.  
21.  // Register another complex parameter that depends on -f and excludes -h
22.  $dir = new ezcConsoleOption(
23.   'd',
24.   'dir',
25.   ezcConsoleInput::TYPE_STRING,
26.   null,
27.   true,
28.   'Process a directory.',
29.   'Processes a complete directory.',
30.   array( new ezcConsoleOptionRule( $optionHandler->getOption( 'f' ) ) ),
31.   array( new ezcConsoleOptionRule( $optionHandler->getOption( 'h' ) ) )
32.  );
33.  $optionHandler->registerOption( $dir );
34.  
35.  // Register an alias for this parameter
36.  $optionHandler->registerAlias( 'e', 'extended-dir', $dir );
37.  
38.  // Process registered parameters and handle errors
39.  try
40.  {
41.       $optionHandler->process( array( 'example_input.php', '-h' ) );
42.  }
43.  catch ( ezcConsoleOptionException $e )
44.  {
45.       echo $e->getMessage();
46.       exit( 1 );
47.  }
48.  
49.  // Process a single parameter
50.  $file = $optionHandler->getOption( 'f' );
51.  if ( $file->value === false )
52.  {
53.       echo "Parameter -{$file->short}/--{$file->long} was not submitted.\n";
54.  }
55.  elseif ( $file->value === true )
56.  {
57.       echo "Parameter -{$file->short}/--{$file->long} was submitted without value.\n";
58.  }
59.  else
60.  {
61.       echo "Parameter -{$file->short}/--{$file->long} was submitted with value '".var_export($file->value, true)."'.\n";
62.  }
63.  
64.  // Process all parameters at once:
65.  foreach ( $optionHandler->getOptionValues() as $paramShort => $val )
66.  {
67.       switch ( true )
68.       {
69.           case $val === false:
70.               echo "Parameter $paramShort was not submitted.\n";
71.               break;
72.           case $val === true:
73.               echo "Parameter $paramShort was submitted without a value.\n";
74.               break;
75.           case is_array( $val ):
76.               echo "Parameter $paramShort was submitted multiple times with value: '".implode(', ', $val)."'.\n";
77.               break;
78.           default:
79.               echo "Parameter $paramShort was submitted with value: '$val'.\n";
80.               break;
81.       }
82.  }

This method returns a part of the program synopsis, specifically for a certain parameter. The method recursively adds depending parameters up to the 2nd depth level to the synopsis. The second parameter is used to store the short names of all options that have already been used in the synopsis (to avoid adding an option twice). The 3rd parameter determines the actual deps in the option dependency recursion to terminate that after 2 recursions.

This method returns all arguments provided to a program in an int indexed array. Arguments are sorted in the way they are submitted to the program. You can disable arguments through the 'arguments' flag of a parameter, if you want to disallow arguments.

Arguments are either the last part of the program call (if the last parameter is not a 'multiple' one) or divided via the '--' method which is commonly used on Unix (if the last parameter accepts multiple values this is required).

This method returns an array of help information for your options, indexed by int. Each help info has 2 fields:

1. => The options names ("<short> / <long>")
2. => The help text (depending on the $long parameter)

If using the second options, you can filter the options shown in the help output (e.g. to show short help for related options). Provide as simple number indexed array of short and/or long values to set a filter.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1.   array(
2.       'First section' => array(
3.           'input',
4.           'output'
5.           'overwrite',
6.       ),
7.       'Second section' => array(
8.           'v',
9.           'h',
10.       ),
11.   )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option is displayed at all.

This method provides the information returned by ezcConsoleInput::getHelp() in a table.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1.   array(
2.       'First section' => array(
3.           'input',
4.           'output'
5.           'overwrite',
6.       ),
7.       'Second section' => array(
8.           'v',
9.           'h',
10.       ),
11.   )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option as displayed at all.

This method generates a help text as it's commonly known from Unix command line programs. The output will contain the synopsis, your provided program description and the selected parameter help as also provided by ezcConsoleInput::getHelp(). The returned string can directly be printed to the console.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1.   array(
2.       'First section' => array(
3.           'input',
4.           'output'
5.           'overwrite',
6.       ),
7.       'Second section' => array(
8.           'v',
9.           'h',
10.       ),
11.   )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option as displayed at all.

This method receives the long or short name of an option and returns the ezcConsoleOption object.

Returns an array of all registered options in the following format:

1.  array(
2.       0 => ezcConsoleOption,
3.       1 => ezcConsoleOption,
4.       2 => ezcConsoleOption,
5.       ...
6.  );

Returns an array of all values submitted to the options. The array is indexed by the parameters short name (excluding the '-' prefix). The array does not contain any parameter, which value is 'false' (meaning: the parameter was not submitted).

This gives you a synopsis definition for the options and arguments defined with this instance of ezcConsoleInput. You can filter the options named in the synopsis by submitting their short names in an array as the parameter of this method. If the parameter $optionNames is set, only those options are listed in the synopsis.

Checks if an option with the given name is registered.

This method returns if an option was submitted, which was defined to be a help option, using the isHelpOption flag.

Actually process the input options and arguments according to the actual settings.

Per default this method uses $argc and $argv for processing. You can override this setting with your own input, if necessary, using the parameters of this method. (Attention, first argument is always the pro gram name itself!)

All exceptions thrown by this method contain an additional attribute "option" which specifies the parameter on which the error occurred.

Registers a new alias for an existing option. Aliases can be used as if they were a normal option.

The alias is registered with the short option name $short and the long option name $long. The alias references to the existing option $option.

This method adds the new option $option to your option collection. If already an option with the assigned short or long value exists, an exception will be thrown.

Accepts a string to define parameters and registers all parameters as options accordingly. String definition, specified in $optionDef, looks like this:

1.  [s:|size:][u:|user:][a:|all:]

This string registers 3 parameters: -s / --size -u / --user -a / --all

This method is called automatically by process(), if this method is called twice or more, and may also be used to manually reset the values of all registered {@ezcConsoleOption} and ezcConsoleArgument objects.

This function removes an alias with the short name $short and long name $long.

This function removes an option. All dependencies to that specific option are removed completely from every other registered option.