README

Minimalist PHP framework to build CLI applications.

Installation

composer require arnapou/console

packagist 👉️ arnapou/console

Introduction

Main ideas:

1. why bother with definitions when you have type-hinting and phpDoc ?
2. explicit command-line arguments
3. open (interfaces everywhere, you can hack and change almost all)
4. KISS (Keep it simple, stupid!")

Type-hinting and phpDoc

phpDoc is used to render the help, only when needed: zero overhead. Near 100% of the time, when we execute our commands, we don't need the doc.

Unlike Symfony console or other similar projects, we don't check the "definition" before running the command: extra flags or parameters are just ignored.

use Arnapou\Console\Application;
use Arnapou\Console\Command\ArrayCommandLoader;

$loader = new ArrayCommandLoader();
$loader->addCommand(
    'dummy',
    /**
     * My dummy command.
     * 
     * @param int $number Dummy parameter
     */
    function (int $number): void {
        echo "dummy parameter = '$number' \n";
    }
);
$app = new Application($loader);
$app->run();

// $ php <file.php> dummy --help
// My dummy command.
// 
// Usage:
//   dummy [parameters] [flags]
// 
// Parameters:
//   number=int  Dummy parameter
// 
// Flags:
//   --colors    Force the use of ansi colors, --no-colors to disable
//   --debug     Print error, warning, success, info, debug
//   --info      Print error, warning, success, info (default)
//   --success   Print error, warning, success
//   --warning   Print error, warning
//   --error     Print error
//   --quiet     Print nothing but exceptions
//   --help      Show help

Explicit command-line arguments

I couldn't find a proper RFC-like around command-line arguments and options.

The closest I could find is around GNU and POSIX, but they have the disadvantages of being too versatile, not enough explicit to my point of view.

Thus, I introduce 2 notions.

Parameters

Inspired from URI query string on the pattern name=value.

👉️ They are injected in the command parameters.

Case of lists

If you repeat a same parameter, it automatically means that this is a list.

Example: foo=1 foo=2 foo=3 will be parsed as foo: ["1", "2", "3"]

Case of array

You can use a "path" notation with a dot as separator to express an array.

Example: user.name=John user.age=20 will be parsed as user: {"name": "John", "age": "20"}

Tip: it reaches its full power when used with DTOs or Value Objects in the command parameter.

Flags

Boolean values on the patterns --flag (true) or --no-flag (false).

👉️ They can be used by any object which need them (TerminalInterface, HelpInterface, ...) to change their behaviour.

Note: you may use them into the command too, if you inject a ArgumentsInterface parameter in your command function signature.

Examples

1. Basic commands with Closure and callable object
2. Injected DTO to show how commands can use DTOs
3. PSR-11 container which can retrieve commands dynamically
4. PSR-11 container which can inject services into the command
5. Single command is possible by setting a default command name

Php versions