Download the PHP package donatj/flags without Composer

Flags

Flags is an argument parser inspired by the Go-lang Flag package, taking its methodology but attaching a GNU-style flag parser.

Flags supports the following style of parameters:

Long-Flags
--key=value / --key value

Short-Flags
-v

GNU Style Multi-Short-Flags
-Xasd

Multiple of the Same Short-Flag
-vvv

As well as the  --  operator for absolute separation of arguments from options.

Requirements

• php: >=7.1.0

Installing

Install the latest version with:

Example

Here is a simple example script:

The by-reference = & allows the value to be updated from the default to the argument value once the parse() method has been triggered. This is inspired by the Go Flag packages use of pointers

Documentation

Class: donatj\Flags

Method: Flags->__construct

Flags constructor.

Parameters:

• array | null $args - The arguments to parse, defaults to $_SERVER['argv']
• bool $skipFirstArgument - Setting to false causes the first argument to be parsed as an parameter rather than the command.

Method: Flags->arg

Returns the n'th command-line argument. arg(0) is the first remaining argument after flags have been processed.

Parameters:

• int $index

Returns:

• string

Method: Flags->args

Returns the non-flag command-line arguments.

Returns:

• string[] - Array of argument strings

Method: Flags->shorts

Returns an array of short-flag call-counts indexed by character

-v would set the 'v' index to 1, whereas -vvv will set the 'v' index to 3

Returns:

• array

Method: Flags->longs

Returns an array of long-flag values indexed by flag name

Returns:

• array

Method: Flags->short

Defines a short-flag of specified name, and usage string.

The return value is a reference to an integer variable that stores the number of times the short-flag was called.

This means the value of the reference for v would be the following.

-v => 1  
-vvv => 3

Parameters:

• string $letter - The character of the short-flag to define
• string $usage - The usage description

Returns:

• int

Method: Flags->bool

Defines a bool long-flag of specified name, default value, and usage string.

The return value is a reference to a variable that stores the value of the flag.

Examples

Truth-y

 --mybool=[true|t|1]  
 --mybool [true|t|1]  
 --mybool  

False-y

 --mybool=[false|f|0]  
 --mybool [false|f|0]  
   [not calling --mybool and having the default false]

Parameters:

• string $name - The name of the long-flag to define
• mixed $value - The default value - usually false for bool - which if null marks the flag required
• string $usage - The usage description

Returns:

• mixed - A reference to the flags value

Method: Flags->float

Defines a float long-flag of specified name, default value, and usage string.

The return value is a reference to a variable that stores the value of the flag.

Examples

--myfloat=1.1  
--myfloat 1.1

Parameters:

• string $name - The name of the long-flag to define
• mixed $value - The default value which if null marks the flag required
• string $usage - The usage description

Returns:

• mixed - A reference to the flags value

Method: Flags->int

Defines an integer long-flag of specified name, default value, and usage string.

The return value is a reference to a variable that stores the value of the flag.

Note: Float values trigger an error, rather than casting.

Examples

--myinteger=1  
--myinteger 1

Parameters:

• string $name - The name of the long-flag to define
• mixed $value - The default value which if null marks the flag required
• string $usage - The usage description

Returns:

• mixed - A reference to the flags value

Method: Flags->uint

Defines a unsigned integer long-flag of specified name, default value, and usage string.

The return value is a reference to a variable that stores the value of the flag.

Note: Negative values trigger an error, rather than casting.

Examples

--myinteger=1  
--myinteger 1

Parameters:

• string $name - The name of the long-flag to define
• mixed $value - The default value which if null marks the flag required
• string $usage - The usage description

Returns:

• mixed - A reference to the flags value

Method: Flags->string

Defines a string long-flag of specified name, default value, and usage string.

The return value is a reference to a variable that stores the value of the flag.

Examples

--mystring=vermouth  
--mystring="blind jazz singers"  
--mystring vermouth  
--mystring "blind jazz singers"

Parameters:

• string $name - The name of the long-flag to define
• mixed $value - The default value which if null marks the flag required
• string $usage - The usage description

Returns:

• mixed - A reference to the flags value

Method: Flags->getDefaults

Returns the default values of all defined command-line flags as a formatted string.

Example

Returns:

• string

Method: Flags->parse

Parses flag definitions from the argument list, which should include the command name.

Must be called after all flags are defined and before flags are accessed by the program.

Will throw exceptions on Missing Require Flags, Unknown Flags or Incorrect Flag Types

Parameters:

• array | null $args - The arguments to parse. Defaults to arguments defined in the constructor.
• bool $ignoreExceptions - Setting to true causes parsing to continue even after an exception has been thrown.
• bool $skipFirstArgument - Option to parse the first argument as an parameter rather than the command. Defaults to constructor value

Throws: \donatj\Exceptions\MissingFlagParamException

Throws: \donatj\Exceptions\InvalidFlagParamException

Throws: \donatj\Exceptions\InvalidFlagTypeException

Method: Flags->parsed

Returns true if the command-line flags have been parsed.

Returns:

• bool