norse-blue/flow

PHP fluid command builder.

dev-master 2019-01-27 04:05 UTC

Requires

• php: ^7.3
• ext-json: *
• myclabs/php-enum: ^1.6

Requires (Dev)

• phpstan/phpstan: ^0.11
• phpunit/phpunit: ^7.5
• squizlabs/php_codesniffer: ^3.4

MIT

• Axel Pardemann

• flow
• command
• builder
• fluid
• NorseBlue

README

About

Flow allows to create command classes that have a fluid interface to set its arguments and options values and get the executable string at the end. Example:

$cmd = new IdCommand();
$cmd->user('axel')->_g(true);
var_dump((string)$cmd);

// Output:
// string(10) "id -g axel"

Installation

Requirements

This package requires the following to work correctly:

• PHP 7.3+
• PHP JSON extension

Require Flow using Composer:

composer require norse-blue/flow

Usage

There are two main ways to use this package, both methods are equivalent.

Inheritance

Create a new command class that inherits from NorseBlue\Flow\Commands\FluidBaseCommand and configure the arguments and options accordingly.

class IdCommand extends FluidBaseCommand
{
    protected $name = 'id';

    protected $arguments_definition = [
      'user' => ArgumentType::STRING,
    ];
  
    protected $options_definition = [
        '-a' => OptionType::BOOL,
        '-Z|--context' => OptionType::BOOL,
        '-g|--group' => OptionType::BOOL,
        '-G|--groups' => OptionType::BOOL,
        '-n|--name' => OptionType::BOOL,
        '-r|--real' => OptionType::BOOL,
        '-u|--user' => OptionType::BOOL,
        '-z|--zero' => OptionType::BOOL,
        '--help' => OptionType::BOOL,
        '--version' => OptionType::BOOL,
    ];
}

Composition

If you can't/won't use inheritance you can include the NorseBlue\Flow\Commands\HandlesCommandInternals trait to your class, configure the arguments and options accordingly and initialize the command anywhere (preferably in the constructor).

class IdCommand
{
    use NorseBlue\Flow\Commands\HandloesCommandInternals;
  
    protected $name = 'id';

    protected $arguments_definition = [
      'user' => ArgumentType::STRING,
    ];
  
    protected $options_definition = [
        '-a' => OptionType::BOOL,
        '-Z|--context' => OptionType::BOOL,
        '-g|--group' => OptionType::BOOL,
        '-G|--groups' => OptionType::BOOL,
        '-n|--name' => OptionType::BOOL,
        '-r|--real' => OptionType::BOOL,
        '-u|--user' => OptionType::BOOL,
        '-z|--zero' => OptionType::BOOL,
        '--help' => OptionType::BOOL,
        '--version' => OptionType::BOOL,
    ];
    
    public function __construct() {
        $this->init($this->arguments_definition ?? [], $this->options_definition ?? []);
    }
}

Command Configuration

The command uses three properties to be configured: name, arguments_definition and options_definition.

Name

This is the commands name. This will be prepended as-is to the resulting string. This name is the name of the command to be executed: id, cat, git, composer, etc.

Arguments definition

This is the definition array for the command arguments. The item's key is how the argument is identified and used for the command calls, e.g. a 'user' entry creates a user method that can be called like $cmd->user('value').

Array structure

// Arguments definition
$arguments_defintiion = [
    {key} => {type},
];
/**
 * {key}: string argument identifier. It has to begin with a letter (either case) and can contain letters, numbers, underscore and dash. It cannot end in a dash. No spaces allowed
 * {type}: string or array. If a string is given then it has to be one of the ArgumentType enum values. If an array is given it has to match the argument spec structure.
 */

// Argument spec structure
$argument_spec = [
    'type' => {type},
    'validation' => {validation},
];
/**
 * {type}: string. One of the ArgumentType enum values.
 * {validation}: \Closure [optional]. A closure that validates the argument value when it is set.
 */

Options definition

This is the definition array for the command options. The item's key is how the option is identified and used for the command calls, e.g. a '-g' entry creates a _g method that can be called like $cmd->_g(true).

Notes:

• The dashes in key names are replaced with underscore when defining the method names. The definition still requires the use of dashes for the keys (as you would for the commands in a terminal).
• PHP function names are case-insensitive, but this package makes the command method names case-sensitive, so $cmd->_g(true) and $cmd->_G(true) may or may not be equivalent (depending on the aliases in the definition).

Array structure

// Options definition
$options_defintiion = [
    {key} => {type},
];
/**
 * {key}: string argument identifier. It must begin with '-' or '--' and a letter (either case). IT can contain letters, numbers, underscore, dash. It cannot end ina  dash. The option can have aliases separating them with '|', e.g. '-f|--flag'. No spaces allowed.
 * {type}: string or array. If a string is given then it has to be one of the OptionType enum values. If an array is given it has to match the option spec structure.
 */

// Option spec structure
$option_spec = [
    'type' => {type},
    'glue' => {glue},
    'validation' => {validation},
];
/**
 * {type}: string. One of the OptionType enum values.
 * {glue}: string [optional]. It is the string that glues the option identifier with its value when converting to string. Usually it does not need to be set. The default value is ' '.
 * {validation}: \Closure [optional]. A closure that validates the option value when it is set.
 */

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

License

Flow is release under the MIT license.