arnapou/console

Library - Minimalist PHP framework to build CLI applications.

v1.0.0 2025-11-05 17:31 UTC

Requires

• php: ~8.3.0 || ~8.4.0 || ~8.5.0
• arnapou/dto: ^4.6
• arnapou/message-templates: ^1.2
• arnapou/psr-clock: ^1.2
• phpstan/phpdoc-parser: ^2.3
• psr/container: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.52
• phpstan/extension-installer: ^1.3
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/php-code-coverage: ^12.0
• phpunit/phpunit: ^12.0

MIT

• Arnaud Buathier

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

Date	Ref	8.5	8.4	8.3
25/10/2025	1.0.x, main	×	×	×