phpdevcommunity/php-console

A lightweight PHP library designed to simplify command handling in console applications.

1.0.7 2025-11-21 09:11 UTC

Requires

• php: >=7.4
• ext-ctype: *
• ext-json: *
• ext-mbstring: *

Requires (Dev)

• depo/unitester: ^1.0.0

MIT

• F. Michel

README

A lightweight PHP library designed to simplify command handling in console applications. This library is dependency-free and focused on providing a streamlined and efficient solution for building PHP CLI tools.

Installation

You can install this library via Composer. Ensure your project meets the minimum PHP version requirement of 7.4.

composer require phpdevcommunity/php-console

Requirements

• PHP version 7.4 or higher

Table of Contents

1. Setup in a PHP Application
2. Creating a Command
3. Defining Arguments and Options
4. Handling Different Output Types

I attempted to rewrite the chapter "Setup in a PHP Application" in English while updating the document, but the update failed due to an issue with the pattern-matching process. Let me fix the issue manually. Here's the rewritten content in English:

Setup in a PHP Application

To use this library in any PHP application (Symfony, Laravel, Slim, or others), first create a bin directory in your project. Then, add a script file, for example, bin/console, with the following content:

#!/usr/bin/php
<?php

use PhpDevCommunity\Console\CommandParser;
use PhpDevCommunity\Console\CommandRunner;
use PhpDevCommunity\Console\Output;

set_time_limit(0);

if (file_exists(dirname(__DIR__) . '/../../autoload.php')) {
    require dirname(__DIR__) . '/../../autoload.php';
} elseif (file_exists(dirname(__DIR__) . '/vendor/autoload.php')) {
    require dirname(__DIR__) . '/vendor/autoload.php';
} else {
    die(
        'You need to set up the project dependencies using the following commands:' . PHP_EOL .
        'curl -sS https://getcomposer.org/installer | php' . PHP_EOL .
        'php composer.phar install' . PHP_EOL
    );
}


// For modern frameworks using containers and bootstrapping (e.g., Kernel or App classes),
// make sure to retrieve the CommandRunner from the container after booting the application.
// Example for Symfony:
//
// $kernel = new Kernel('dev', true);
// $kernel->boot();
// $container = $kernel->getContainer();
// $app = $container->get(CommandRunner::class);


$app = new CommandRunner([]);
$exitCode = $app->run(new CommandParser(), new Output());
exit($exitCode);

By convention, the file is named bin/console, but you can choose any name you prefer. This script serves as the main entry point for your CLI commands. Make sure the file is executable by running the following command:

chmod +x bin/console

Creating a Command

To add a command to your application, you need to create a class that implements the CommandInterface interface. Here is an example implementation for a command called send-email:

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\OutputInterface;

class SendEmailCommand implements CommandInterface
{
    public function getName(): string
    {
        return 'send-email';
    }

    public function getDescription(): string
    {
        return 'Sends an email to the specified recipient with an optional subject.';
    }

    public function getOptions(): array
    {
        return [
            new CommandOption('subject', 's', 'The subject of the email', false),
        ];
    }

    public function getArguments(): array
    {
        return [
            new CommandArgument('recipient', true, null, 'The email address of the recipient'),
        ];
    }

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        // Validate and retrieve the recipient email
        if (!$input->hasArgument('recipient')) {
            $output->writeln('Error: The recipient email is required.');
            return;
        }
        $recipient = $input->getArgumentValue('recipient');

        // Validate email format
        if (!filter_var($recipient, FILTER_VALIDATE_EMAIL)) {
            $output->writeln('Error: The provided email address is not valid.');
            return;
        }

        // Retrieve the subject option (if provided)
        $subject = $input->hasOption('subject') ? $input->getOptionValue('subject') : 'No subject';

        // Simulate email sending
        $output->writeln('Sending email...');
        $output->writeln('Recipient: ' . $recipient);
        $output->writeln('Subject: ' . $subject);
        $output->writeln('Email sent successfully!');
    }
}

Registering the Command in CommandRunner

After creating your command, you need to register it in the CommandRunner so that it can be executed. Here is an example of how to register the SendEmailCommand:

use PhpDevCommunity\Console\CommandRunner;

$app = new CommandRunner([
    new SendEmailCommand()
]);

The CommandRunner takes an array of commands as its parameter. Each command should be an instance of a class that implements the CommandInterface. Once registered, the command can be called from the console.

Example Usage in the Terminal

1. Command without a subject option:

   bin/console send-email [e-mail]

   Output:

   Sending email...
   Recipient: [e-mail]
   Subject: No subject
   Email sent successfully!
   

2. Command with a subject option:

   bin/console send-email [e-mail] --subject "Meeting Reminder"

   Output:

   Sending email...
   Recipient: [e-mail]
   Subject: Meeting Reminder
   Email sent successfully!
   

3. Command with an invalid email format:

   bin/console send-email invalid-email

   Output:

   Error: The provided email address is not valid.
   

4. Command without the required argument:

   bin/console send-email

   Output:

   Error: The recipient email is required.
   

Explanation of the Features Used

1. Required Arguments:

   • The recipient argument is mandatory. If missing, the command displays an error.

2. Optional Options:

   • The --subject option allows defining the subject of the email. If not specified, a default value ("No subject") is used.

3. Simple Validation:

   • The email address is validated using filter_var to ensure it has a valid format.

4. User Feedback:

   • Clear and simple messages are displayed to guide the user during the command execution.

Defining Arguments and Options

Arguments and options allow developers to customize the behavior of a command based on the parameters passed to it. These concepts are managed by the CommandArgument and CommandOption classes, respectively.

1 Arguments

An argument is a positional parameter passed to a command. For example, in the following command:

bin/console send-email [e-mail]

[e-mail] is an argument. Arguments are defined using the CommandArgument class. Here are the main properties of an argument:

• Name (name): The unique name of the argument.
• Required (isRequired): Indicates whether the argument is mandatory.
• Default Value (defaultValue): The value used if no argument is provided.
• Description (description): A brief description of the argument, useful for help messages.

Example of defining an argument:

use PhpDevCommunity\Console\Argument\CommandArgument;

new CommandArgument(
    'recipient', // The name of the argument
    true,        // The argument is required
    null,        // No default value
    'The email address of the recipient' // Description
);

If a required argument is not provided, an exception is thrown.

2 Options

An option is a named parameter, often prefixed with a double dash (--) or a shortcut (-). For example, in the following command:

bin/console send-email [e-mail] --subject "Meeting Reminder"

--subject is an option. Options are defined using the CommandOption class. Here are the main properties of an option:

• Name (name): The full name of the option, used with --.
• Shortcut (shortcut): A short alias, used with a single dash (-).
• Description (description): A brief description of the option, useful for help messages.
• Flag (isFlag): Indicates whether the option is a simple flag (present or absent) or if it accepts a value.

Example of defining an option:

use PhpDevCommunity\Console\Option\CommandOption;

new CommandOption(
    'subject',    // The name of the option
    's',          // Shortcut
    'The subject of the email', // Description
    false         // Not a flag, expects a value
);

new CommandOption(
    'verbose',    // The name of the option
    'v',          // Shortcut
    'Enable verbose output', // Description
    true          // This is a flag
);

An option with a flag does not accept a value; its mere presence indicates that it is enabled.

3 Usage in a Command

In a command, arguments and options are defined by overriding the getArguments() and getOptions() methods from the CommandInterface.

Example:

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Option\CommandOption;

public function getArguments(): array
{
    return [
        new CommandArgument('recipient', true, null, 'The email address of the recipient'),
    ];
}

public function getOptions(): array
{
    return [
        new CommandOption('subject', 's', 'The subject of the email', false),
        new CommandOption('verbose', 'v', 'Enable verbose output', true),
    ];
}

In this example:

• recipient is a required argument.
• --subject (or -s) is an option that expects a value.
• --verbose (or -v) is a flag option.

4 Validation and Management

Arguments and options are automatically validated when the command is executed. For instance, if a required argument is missing or an attempt is made to access an undefined option, an exception will be thrown.

The InputInterface allows you to retrieve these parameters in the execute method:

• Arguments: $input->getArgumentValue('recipient')
• Options: $input->getOptionValue('subject') or $input->hasOption('verbose')

This ensures clear and consistent management of the parameters passed within your PHP project.

Handling Different Output Types

Output management provides clear and useful information during command execution. Below is a practical example demonstrating output functionalities.

Example: Command UserReportCommand

This command generates a report for a specific user and uses various output features.

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\Output\ConsoleOutput;
use PhpDevCommunity\Console\OutputInterface;

class UserReportCommand implements CommandInterface
{
    public function getName(): string
    {
        return 'user:report';
    }

    public function getDescription(): string
    {
        return 'Generates a detailed report for a specific user.';
    }

    public function getArguments(): array
    {
        return [
            new CommandArgument('user_id', true, null, 'The ID of the user to generate the report for'),
        ];
    }

    public function getOptions(): array
    {
        return [
            new CommandOption('verbose', 'v', 'Enable verbose output', true),
            new CommandOption('export', 'e', 'Export the report to a file', false),
        ];
    }

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        $console = new ConsoleOutput($output);

        // Main title
        $console->title('User Report Generation');

        // Arguments and options
        $userId = $input->getArgumentValue('user_id');
        $verbose = $input->hasOption('verbose');
        $export = $input->hasOption('export') ? $input->getOptionValue('export') : null;

        $console->info("Generating report for User ID: $userId");

        // Simulating user data retrieval
        $console->spinner();
        $userData = [
            'name' => 'John Doe',
            'email' => '[e-mail]',
            'active' => true,
            'roles' => ['admin', 'user']
        ];

        if ($verbose) {
            $console->success('User data retrieved successfully.');
        }

        // Displaying user data
        $console->json($userData);

        // Displaying user roles as a list
        $console->listKeyValues([
            'Name' => $userData['name'],
            'Email' => $userData['email'],
            'Active' => $userData['active'] ? 'Yes' : 'No',
        ]);
        $console->list($userData['roles']);

        // Table of recent activities
        $headers = ['ID', 'Activity', 'Timestamp'];
        $rows = [
            ['1', 'Login', '2024-12-22 12:00:00'],
            ['2', 'Update Profile', '2024-12-22 12:30:00'],
        ];
        $console->table($headers, $rows);

        // Progress bar
        for ($i = 0; $i <= 100; $i += 20) {
            $console->progressBar(100, $i);
            usleep(500000);
        }

        // Final result
        if ($export) {
            $console->success("Report exported to: $export");
```php
use PhpDevCommunity\Console\Argument\CommandArgument;

// Using the constructor
new CommandArgument(
    'recipient', // The name of the argument
    true,        // The argument is required
    null,        // No default value
    'The email address of the recipient' // Description
);

// Using static methods (Recommended)
CommandArgument::required('recipient', 'The email address of the recipient');
CommandArgument::optional('recipient', null, 'The email address of the recipient');

If a required argument is not provided, an exception is thrown.

2 Options

An option is a named parameter, often prefixed with a double dash (--) or a shortcut (-). For example, in the following command:

bin/console send-email [e-mail] --subject "Meeting Reminder"

--subject is an option. Options are defined using the CommandOption class. Here are the main properties of an option:

Example of defining an option:

use PhpDevCommunity\Console\Option\CommandOption;

new CommandOption(
    'subject',    // The name of the option
    's',          // Shortcut
    'The subject of the email', // Description
    false         // Not a flag, expects a value
);

An option with a flag does not accept a value; its mere presence indicates that it is enabled.

3 Usage in a Command

In a command, arguments and options are defined by overriding the getArguments() and getOptions() methods from the CommandInterface.

Example:

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Option\CommandOption;

public function getArguments(): array
{
    return [
        new CommandArgument('recipient', true, null, 'The email address of the recipient'),
    ];
}

public function getOptions(): array
{
    return [
        new CommandOption('subject', 's', 'The subject of the email', false),
    ];
}

In this example:

• recipient is a required argument.
• --subject (or -s) is an option that expects a value.

Note

Global Options: The options --help (-h) and --verbose (-v) are globally available for all commands. You must not define them manually in your commands, as they are automatically handled by the application.

4 Validation and Management

Arguments and options are automatically validated when the command is executed. For instance, if a required argument is missing or an attempt is made to access an undefined option, an exception will be thrown.

The InputInterface allows you to retrieve these parameters in the execute method:

• Arguments: $input->getArgumentValue('recipient')
• Options: $input->getOptionValue('subject') or $input->hasOption('verbose')

This ensures clear and consistent management of the parameters passed within your PHP project.

Handling Different Output Types

Output management provides clear and useful information during command execution. Below is a practical example demonstrating output functionalities.

Example: Command UserReportCommand

This command generates a report for a specific user and uses various output features.

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\Output\ConsoleOutput;
use PhpDevCommunity\Console\OutputInterface;

class UserReportCommand implements CommandInterface
{
    public function getName(): string
    {
        return 'user:report';
    }

    public function getDescription(): string
    {
        return 'Generates a detailed report for a specific user.';
    }

    public function getArguments(): array
    {
        return [
            new CommandArgument('user_id', true, null, 'The ID of the user to generate the report for'),
        ];
    }

    public function getOptions(): array
    {
        return [
            new CommandOption('export', 'e', 'Export the report to a file', false),
        ];
    }

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        $console = new ConsoleOutput($output);

        // Main title
        $console->title('User Report Generation');

        // Arguments and options
        $userId = $input->getArgumentValue('user_id');
        $verbose = $input->hasOption('verbose'); // Available globally
        $export = $input->hasOption('export') ? $input->getOptionValue('export') : null;

        $console->info("Generating report for User ID: $userId");

        // Simulating user data retrieval
        $console->spinner();
        $userData = [
            'name' => 'John Doe',
            'email' => '[e-mail]',
            'active' => true,
            'roles' => ['admin', 'user']
        ];

        if ($verbose) {
            $console->debug('User data retrieved successfully.');
        }

        // Displaying user data
        $console->json($userData);

        // Displaying user roles as a list
        $console->listKeyValues([
            'Name' => $userData['name'],
            'Email' => $userData['email'],
            'Active' => $userData['active'] ? 'Yes' : 'No',
        ]);
        $console->list($userData['roles']);

        // Table of recent activities
        $headers = ['ID', 'Activity', 'Timestamp'];
        $rows = [
            ['1', 'Login', '2024-12-22 12:00:00'],
            ['2', 'Update Profile', '2024-12-22 12:30:00'],
        ];
        $console->table($headers, $rows);

        // Progress bar
        for ($i = 0; $i <= 100; $i += 20) {
            $console->progressBar(100, $i);
            usleep(500000);
        }

        // Final result
        if ($export) {
            $console->success("Report exported to: $export");
```php
use PhpDevCommunity\Console\Argument\CommandArgument;

// Using the constructor
new CommandArgument(
    'recipient', // The name of the argument
    true,        // The argument is required
    null,        // No default value
    'The email address of the recipient' // Description
);

// Using static methods (Recommended)
CommandArgument::required('recipient', 'The email address of the recipient');
CommandArgument::optional('recipient', null, 'The email address of the recipient');

If a required argument is not provided, an exception is thrown.

2 Options

An option is a named parameter, often prefixed with a double dash (--) or a shortcut (-). For example, in the following command:

bin/console send-email [e-mail] --subject "Meeting Reminder"

--subject is an option. Options are defined using the CommandOption class. Here are the main properties of an option:

• Name (name): The full name of the option, used with --.
• Shortcut (shortcut): A short alias, used with a single dash (-).
• Description (description): A brief description of the option, useful for help messages.
• Flag (isFlag): Indicates whether the option is a simple flag (present or absent) or if it accepts a value.

Example of defining an option:

use PhpDevCommunity\Console\Option\CommandOption;

// Using the constructor
new CommandOption(
    'subject',    // The name of the option
    's',          // Shortcut
    'The subject of the email', // Description
    false         // Not a flag, expects a value
);

// Using static methods (Recommended)
CommandOption::withValue('subject', 's', 'The subject of the email');

An option with a flag does not accept a value; its mere presence indicates that it is enabled.

3 Usage in a Command

In a command, arguments and options are defined by overriding the getArguments() and getOptions() methods from the CommandInterface.

Example:

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Option\CommandOption;

public function getArguments(): array
{
    return [
        CommandArgument::required('recipient', 'The email address of the recipient'),
    ];
}

public function getOptions(): array
{
    return [
        CommandOption::withValue('subject', 's', 'The subject of the email'),
    ];
}

In this example:

• recipient is a required argument.
• --subject (or -s) is an option that expects a value.

Note

Global Options: The options --help (-h) and --verbose (-v) are globally available for all commands. You must not define them manually in your commands, as they are automatically handled by the application.

4 Validation and Management

Arguments and options are automatically validated when the command is executed. For instance, if a required argument is missing, an exception will be thrown.

The InputInterface allows you to retrieve these parameters in the execute method:

• Arguments: $input->getArgumentValue('recipient') (Throws exception if missing and required)
• Options: $input->getOptionValue('subject') (Returns null if not present) or $input->hasOption('verbose')

This ensures clear and consistent management of the parameters passed within your PHP project.

Handling Different Output Types

Output management provides clear and useful information during command execution. Below is a practical example demonstrating output functionalities.

Example: Command UserReportCommand

This command generates a report for a specific user and uses various output features.

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\Output\ConsoleOutput;
use PhpDevCommunity\Console\OutputInterface;

class UserReportCommand implements CommandInterface
{
    public function getName(): string
    {
        return 'user:report';
    }

    public function getDescription(): string
    {
        return 'Generates a detailed report for a specific user.';
    }

    public function getArguments(): array
    {
        return [
            CommandArgument::required('user_id', 'The ID of the user to generate the report for'),
        ];
    }

    public function getOptions(): array
    {
        return [
            CommandOption::withValue('export', 'e', 'Export the report to a file'),
        ];
    }

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        $console = new ConsoleOutput($output);

        // Main title
        $console->title('User Report Generation');

        // Arguments and options
        $userId = $input->getArgumentValue('user_id');
        $verbose = $input->hasOption('verbose'); // Available globally
        $export = $input->getOptionValue('export'); // Returns null if not set

        $console->info("Generating report for User ID: $userId");

        // Simulating user data retrieval
        $console->spinner();
        $userData = [
            'name' => 'John Doe',
            'email' => '[e-mail]',
            'active' => true,
            'roles' => ['admin', 'user']
        ];

        if ($verbose) {
            $console->debug('User data retrieved successfully.');
        }

        // Displaying user data
        $console->json($userData);

        // Displaying user roles as a list
        $console->listKeyValues([
            'Name' => $userData['name'],
            'Email' => $userData['email'],
            'Active' => $userData['active'] ? 'Yes' : 'No',
        ]);
        $console->list($userData['roles']);

        // Table of recent activities
        $headers = ['ID', 'Activity', 'Timestamp'];
        $rows = [
            ['1', 'Login', '2024-12-22 12:00:00'],
            ['2', 'Update Profile', '2024-12-22 12:30:00'],
        ];
        $console->table($headers, $rows);

        // Progress bar
        for ($i = 0; $i <= 100; $i += 20) {
            $console->progressBar(100, $i);
            usleep(500000);
        }

        // Final result
        if ($export) {
            $console->success("Report exported to: $export");
        } else {
            $console->success('Report generated successfully!');
        }

        // Confirmation for deletion
        if ($console->confirm('Do you want to delete this user?')) {
            $console->success('User deleted successfully.');
        } else {
            $console->warning('User deletion canceled.');
        }
    }
}

Features Used

1. Rich Messages:

   • success($message): Displays a success message.
   • warning($message): Displays a warning message.
   • error($message): Displays a critical error message.
   • info($message): Displays an informational message.
   • debug($message): Displays a debug message (only visible with -v).
   • title($title): Displays a main title.

2. Structured Output:

   • json($data): Displays data in JSON format.
   • list($items): Displays a simple list.
   • listKeyValues($data): Displays key-value pairs.
   • table($headers, $rows): Displays tabular data.

3. Progression and Interactivity:

   • progressBar($total, $current): Displays a progress bar.
   • spinner(): Displays a loading spinner.
   • confirm($question): Prompts for user confirmation.

Verbosity and Error Handling

• Global Verbosity: The -v or --verbose flag is globally available for all commands. You do not need to define it. Passing it will enable debug() messages.
• Error Handling: The error() method writes messages to STDERR, allowing you to separate error output from standard output (useful for piping).

Documentation en Français

Une bibliothèque PHP légère conçue pour simplifier la gestion des commandes dans les applications console. Cette bibliothèque est sans dépendance et se concentre sur une solution rationalisée et efficace pour créer des outils CLI en PHP.

Installation

Vous pouvez installer cette bibliothèque via Composer. Assurez-vous que votre projet respecte la version minimale de PHP requise (7.4).

composer require phpdevcommunity/php-console

Prérequis

• Version PHP 7.4 ou supérieure

Table des Matières

1. Configuration dans une Application PHP
2. Créer une Commande
3. Définir des Arguments et des Options
4. Gérer les Différents Types de Sortie

Configuration dans une Application PHP

Pour utiliser cette bibliothèque dans n'importe quelle application PHP (Symfony, Laravel, Slim ou autres), créez d'abord un répertoire bin dans votre projet. Ensuite, ajoutez un fichier de script, par exemple bin/console, avec le contenu suivant :

#!/usr/bin/php
<?php

use PhpDevCommunity\Console\CommandParser;
use PhpDevCommunity\Console\CommandRunner;
use PhpDevCommunity\Console\Output;

set_time_limit(0);

if (file_exists(dirname(__DIR__) . '/../../autoload.php')) {
    require dirname(__DIR__) . '/../../autoload.php';
} elseif (file_exists(dirname(__DIR__) . '/vendor/autoload.php')) {
    require dirname(__DIR__) . '/vendor/autoload.php';
} else {
    die(
        'Vous devez installer les dépendances du projet avec les commandes suivantes :' . PHP_EOL .
        'curl -sS https://getcomposer.org/installer | php' . PHP_EOL .
        'php composer.phar install' . PHP_EOL
    );
}

// Pour les frameworks modernes utilisant des conteneurs (ex: Kernel ou App classes),
// assurez-vous de récupérer le CommandRunner depuis le conteneur après le démarrage de l'application.
// Exemple pour Symfony :
//
// $kernel = new Kernel('dev', true);
// $kernel->boot();
// $container = $kernel->getContainer();
// $app = $container->get(CommandRunner::class);


$app = new CommandRunner([]);
$exitCode = $app->run(new CommandParser(), new Output());
exit($exitCode);

Par convention, le fichier est nommé bin/console, mais vous pouvez choisir le nom que vous préférez. Ce script sert de point d'entrée principal pour vos commandes CLI. Assurez-vous que le fichier est exécutable en lançant la commande suivante :

chmod +x bin/console

Créer une Commande

Pour ajouter une commande à votre application, vous devez créer une classe qui implémente l'interface CommandInterface. Voici un exemple d'implémentation pour une commande appelée send-email :

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\OutputInterface;

class SendEmailCommand implements CommandInterface
{
    public function getName(): string
    {
        return 'send-email';
    }

    public function getDescription(): string
    {
        return 'Envoie un email au destinataire spécifié avec un sujet optionnel.';
    }

    public function getOptions(): array
    {
        return [
            CommandOption::withValue('subject', 's', "Le sujet de l'email"),
        ];
    }

    public function getArguments(): array
    {
        return [
            CommandArgument::required('recipient', "L'adresse email du destinataire"),
        ];
    }

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        // Valider et récupérer l'email du destinataire
        if (!$input->hasArgument('recipient')) {
            $output->writeln("Erreur : L'email du destinataire est requis.");
            return;
        }
        $recipient = $input->getArgumentValue('recipient');

        // Valider le format de l'email
        if (!filter_var($recipient, FILTER_VALIDATE_EMAIL)) {
            $output->writeln("Erreur : L'adresse email fournie n'est pas valide.");
            return;
        }

        // Récupérer l'option sujet (si fournie)
        $subject = $input->getOptionValue('subject') ?? 'Pas de sujet';

        // Simuler l'envoi de l'email
        $output->writeln("Envoi de l'email...");
        $output->writeln('Destinataire : ' . $recipient);
        $output->writeln('Sujet : ' . $subject);
        $output->writeln('Email envoyé avec succès !');
    }
}

Enregistrer la Commande dans CommandRunner

Après avoir créé votre commande, vous devez l'enregistrer dans le CommandRunner pour qu'elle puisse être exécutée. Voici un exemple :

use PhpDevCommunity\Console\CommandRunner;

$app = new CommandRunner([
    new SendEmailCommand()
]);

Le CommandRunner prend un tableau de commandes en paramètre. Chaque commande doit être une instance d'une classe implémentant CommandInterface. Une fois enregistrée, la commande peut être appelée depuis la console.

Exemple d'Utilisation dans le Terminal

1. Commande sans option sujet :

   bin/console send-email [e-mail]

   Sortie :

   Envoi de l'email...
   Destinataire : [e-mail]
   Sujet : Pas de sujet
   Email envoyé avec succès !
   

2. Commande avec option sujet :

   bin/console send-email [e-mail] --subject "Rappel de Réunion"

   Sortie :

   Envoi de l'email...
   Destinataire : [e-mail]
   Sujet : Rappel de Réunion
   Email envoyé avec succès !
   

3. Commande avec format d'email invalide :

   bin/console send-email invalid-email

   Sortie :

   Erreur : L'adresse email fournie n'est pas valide.
   

Définir des Arguments et des Options

Les arguments et les options permettent aux développeurs de personnaliser le comportement d'une commande en fonction des paramètres passés. Ces concepts sont gérés respectivement par les classes CommandArgument et CommandOption.

1 Arguments

Un argument est un paramètre positionnel passé à une commande. Par exemple :

bin/console send-email [e-mail]

[e-mail] est un argument. Les arguments sont définis via la classe CommandArgument. Voici les propriétés principales :

• Nom (name) : Le nom unique de l'argument.
• Requis (isRequired) : Indique si l'argument est obligatoire.
• Valeur par défaut (defaultValue) : La valeur utilisée si aucun argument n'est fourni.
• Description (description) : Une brève description de l'argument.

Exemple de définition d'un argument :

use PhpDevCommunity\Console\Argument\CommandArgument;

// Via le constructeur
new CommandArgument(
    'recipient', // Le nom de l'argument
    true,        // L'argument est requis
    null,        // Pas de valeur par défaut
    "L'adresse email du destinataire" // Description
);

// Via les méthodes statiques (Recommandé)
CommandArgument::required('recipient', "L'adresse email du destinataire");
CommandArgument::optional('recipient', null, "L'adresse email du destinataire");

2 Options

Une option est un paramètre nommé, souvent préfixé par un double tiret (--) ou un raccourci (-). Par exemple :

bin/console send-email [e-mail] --subject "Rappel de Réunion"

--subject est une option. Les options sont définies via la classe CommandOption. Voici les propriétés principales :

• Nom (name) : Le nom complet de l'option.
• Raccourci (shortcut) : Un alias court.
• Description (description) : Une brève description.
• Drapeau (isFlag) : Indique si l'option est un simple drapeau (présent ou absent) ou si elle attend une valeur.

Exemple de définition d'une option :

use PhpDevCommunity\Console\Option\CommandOption;

// Via le constructeur
new CommandOption(
    'subject',    // Le nom de l'option
    's',          // Raccourci
    "Le sujet de l'email", // Description
    false         // Ce n'est pas un drapeau, attend une valeur
);

// Via les méthodes statiques (Recommandé)
CommandOption::withValue('subject', 's', "Le sujet de l'email");

Une option avec un drapeau n'accepte pas de valeur ; sa simple présence indique qu'elle est activée.

3 Utilisation dans une Commande

Dans une commande, les arguments et options sont définis en surchargeant les méthodes getArguments() et getOptions() de l'interface CommandInterface.

Exemple :

public function getArguments(): array
{
    return [
        CommandArgument::required('recipient', "L'adresse email du destinataire"),
    ];
}

public function getOptions(): array
{
    return [
        CommandOption::withValue('subject', 's', "Le sujet de l'email"),
    ];
}

Dans cet exemple :

• recipient est un argument requis.
• --subject (ou -s) est une option qui attend une valeur.

Note

Options Globales : Les options --help (-h) et --verbose (-v) sont disponibles globalement pour toutes les commandes. Vous ne devez pas les définir manuellement dans vos commandes, car elles sont gérées automatiquement par l'application.

4 Validation et Gestion

Les arguments et options sont automatiquement validés lors de l'exécution de la commande. L'InputInterface permet de récupérer ces paramètres dans la méthode execute :

• Arguments : $input->getArgumentValue('recipient') (Lève une exception si manquant et requis)
• Options : $input->getOptionValue('subject') (Retourne null si absent) ou $input->hasOption('verbose')

Gérer les Différents Types de Sortie

La gestion de la sortie fournit des informations claires et utiles pendant l'exécution de la commande.

Exemple : Commande UserReportCommand

use PhpDevCommunity\Console\Argument\CommandArgument;
use PhpDevCommunity\Console\Command\CommandInterface;
use PhpDevCommunity\Console\InputInterface;
use PhpDevCommunity\Console\Option\CommandOption;
use PhpDevCommunity\Console\Output\ConsoleOutput;
use PhpDevCommunity\Console\OutputInterface;

class UserReportCommand implements CommandInterface
{
    // ... (méthodes getName, getDescription, getArguments, getOptions comme ci-dessus)

    public function execute(InputInterface $input, OutputInterface $output): void
    {
        $console = new ConsoleOutput($output);

        // Titre principal
        $console->title('Génération du Rapport Utilisateur');

        $userId = $input->getArgumentValue('user_id');
        $verbose = $input->hasOption('verbose'); // Disponible globalement
        $export = $input->getOptionValue('export'); // Retourne null si non défini

        $console->info("Génération du rapport pour l'ID Utilisateur : $userId");

        // Spinner
        $console->spinner();

        if ($verbose) {
            $console->debug('Données utilisateur récupérées avec succès.');
        }

        // Affichage des données
        $console->success('Rapport généré avec succès !');
    }
}

Fonctionnalités Utilisées

1. Messages Riches :

   • success($message) : Affiche un message de succès.
   • warning($message) : Affiche un message d'avertissement.
   • error($message) : Affiche un message d'erreur critique (sur STDERR).
   • info($message) : Affiche un message d'information.
   • debug($message) : Affiche un message de debug (visible uniquement avec -v).
   • title($title) : Affiche un titre principal.

2. Sortie Structurée :

   • json($data) : Affiche des données au format JSON.
   • list($items) : Affiche une liste simple.
   • listKeyValues($data) : Affiche des paires clé-valeur.
   • table($headers, $rows) : Affiche des données tabulaires.

3. Progression et Interactivité :

   • progressBar($total, $current) : Affiche une barre de progression.
   • spinner() : Affiche un spinner de chargement.
   • confirm($question) : Demande une confirmation à l'utilisateur.

Verbosité et Gestion des Erreurs

• Verbosité Globale : Le drapeau -v ou --verbose est disponible globalement pour toutes les commandes. Vous n'avez pas besoin de le définir. L'utiliser activera les messages debug().(This line is already debug, so no change needed here, but I'll double check the context).
• Gestion des Erreurs : La méthode error() écrit les messages sur STDERR, ce qui permet de séparer la sortie d'erreur de la sortie standard (utile pour les pipes).

Licence

Cette bibliothèque est un logiciel open-source sous licence MIT.