rayanlevert/command-line-interface

Dependency-free command line interface (CLI) handling arguments and easily personalizing output in the PHP userland

v2.1.0 2024-04-19 14:59 UTC

Requires

• php: >=8.1
• ext-mbstring: *

Requires (Dev)

• phpstan/phpstan: ^1.9
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

BSD-3-Clause

• Rayan Levert

README

RayanLevert\Cli\Arguments\Argument defines what is an Argument

An argument has a name and different options and can only be of type integer, double ou string (if the option noValue is used, it will be bool)

new \RayanLevert\Cli\Arguments\Argument(string $name, array $options = [])

- description (string) Description of the argument
- defaultValue (float|int|string) Default value if the argument is not handled
- required (bool) If the argument must be present and parsed
- castTo (string) PHP type - If the argument has a type other than string, its value will be casted
- noValue (bool) If a prefixed argument doesn't need a value -> boolean cast
- prefix (string) Short prefix (-u)
- longPrefix (string) Long prefix (--user)

A RayanLevert\Cli\Arguments\Exception can be thrown if options are not compliant (see __construct())

RayanLevert\Cli\Arguments is a collection of Argument capable of parsing values from argv (array of strings)

new \RayanLevert\Cli\Arguments(\RayanLevert\Cli\Arguments\Argument ...$oArguments)

Required arguments must be declared first, before not required ones

Recovery of parsed values is done via the method parse(string ...$arguments): void

To parse arguments from the actual CLI, use parse(...$argv) (with declaring global $argv; if you are not in the global scope)

Associates each parsed value to its Argument in the collection

The parsed value of an argument is recoverable by ::get(string $argumentName)

By default, NULL is returned; integer, float or string can be returned if the argument has been parsed and option castTo has been set

• If castTo is integer or float, the value must be a numeric string (asserts with is_numeric())
• Si castTo is string (by default), the value will be the one parsed

Implementation

$oArguments = new Arguments(new Argument('arg1'));
$oArguments->get('arg1') // NULL

$oArguments = new Arguments(new Argument('arg1', ['defaultValue' => 'test']));
$oArguments->get('arg1') // test

$oArguments = new Arguments(new Argument('arg1', ['castTo' => 'float', 'defaultValue' => 14.3]));
$oArguments->get('arg1') // 14.3

$oArguments = new Arguments(new Argument('arg1', ['required' => true]));
$oArguments->parse(); // ParseException arg1 is required
$oArguments->parse('test'); // OK $oArguments->get('arg1') = test

// Parsing optional arguments
$oArguments = new Arguments(new Argument('arg1'), new Argument('arg2'));
$oArguments->parse('test1'); // $oArguments->get('arg1') = test1, $oArguments->get('arg1') = NULL
$oArguments->parse('test1', 'test2'); // $oArguments->get('arg1') = test1, $oArguments->get('arg1') = test2

// Parsing prefixed arguments
$oArguments = new Arguments(new Argument('arg1', ['prefix' => 'a', 'longPrefix' => 'arg']));
$oArguments->parse('-a=testValue'); // $oArguments->get('arg1') = testValue
$oArguments->parse('-a="test Value"'); // $oArguments->get('arg1') = test Value
$oArguments->parse('--arg=testValue'); // $oArguments->get('arg1') = testValue
$oArguments->parse('--arg="test Value"'); // $oArguments->get('arg1') = test Value

Multiple methods are available

• Adds an argument - set(Argument $oArgument): void
• Removes one - remove(string $argumentName): void
• Returns the number of arguments count(): int
• Prints a clean display about the informations of arguments printArguments(): void

    Required arguments:
      arg1 (type: string)
      arg2 (type: integer)
  
    Optional arguments:
      arg3 --arg3=arg3 (type: integer)
      arg4 -arg4
  

Personalizes the command line interface by changing the color and formatting displayed text

RayanLevert\Cli\Style is a class that only has static methods

3 enumerations are available to stylize the output:

• RayanLevert\Cli\Style\Background: Background colors
• RayanLevert\Cli\Style\Foreground: Text colors
• RayanLevert\Cli\Style\Attributes: Text attributes

2 main methods are used to display formatted text

/**
 * Prints a string of a background color, text color and/or an attribute
*/
public static function inline(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): void;

/**
 * Prints a string and breaks a line of a background color, text color and/or an attribute
*/
public static function outline(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): void;

And one to return the formatted string instead of printing it

public static function stylize(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): string;

Other useful methods are available:

/**
 * Prints a formatted string thanks to its tags of ANSI codes (Foreground, Background and Attribute)
 *
 * Useful is you want to use multiple styles in one single method call
 *
 * Tags to use are in the three enumerations thanks to the 'tryFromTag' method
*/
public static function tag(string $tag): void

====================================
｡◕‿◕｡ This is a title ｡◕‿◕｡
====================================
public static function title(string $title): void;

--- Flanked message ---\n
public static function flank(string $message, string $char = '-', int $length = 3): void;

  (◍•﹏•) Warning message\n
public static function warning(string $message): void; // colored text in yellow

  (◍•﹏•) Error message\n
public static function error(string $message): void; // colored text in red

public static function red(string $message): void; // displays a red colored text and breaks a line
public static function green(string $message): void; // displays a green colored text and breaks a line
public static function yellow(string $message): void; // displays a yellow colored text and breaks a line

// Displays according to a boolean status, a red or green text colored message and breaks a line
public static function outlineWithBool(bool $status, string $ifTrue, string $ifFalse, string $toPrecede = ''): void;

// Prints the details of an exception in red + its trace in white
public static function exception(\Exception $e, bool $withoutTrace = false): void;

RayanLevert\Cli\ProgressBar displays progression output through a progress bar

/**
 * @param int $max Maximum value of iterations
 * @param int $numberOfSymbols Number of symbols added after each iteration
*/
$oProgressBar = new ProgressBar(int $max, int $numberOfSymbols = 50);

/**
 * @param string $title Title to add above the progress bar
 * @param Style\Foreground $fg Text color
*/
$oProgressBar->setTitle(string $title = '', Style\Foreground $fg = Style\Foreground::BLUE);

/**
 * Starts the progress bar (or restarts it, if not breaks two lines)
*/
$oProgressBar->start();

/**
 * Advances the progress bar of `$toAdvance` iterations updating the progression
*/
$oProgressBar->advance(int $toAdvance = 1);

// Finishes the progress bar (advances to the max value)
$oProgressBar->finish();

Simple implementation

// 10 is the max value -> a new symbol every new iteration
$oProgressBar = new ProgressBar(10);
$oProgressBar->start('My progress bar');

// Advances to 1 each iteration
foreach (range(1, 10) as $range) {
    $oProgressBar->advance();
}

  My progress bar
  1 / 10 [#         ]
  2 / 10 [##        ]
  ...
  10 / 10 [##########]