Architecture Console et cycle de vie d'une commande

Un Command Symfony suit un cycle de vie en 4 phases — configure, initialize, interact, execute — et s'intègre dans une Application qui gère le routing et l'I/O.

Le composant Console Symfony est plus qu'une simple bibliothèque de parsing — c'est un mini-framework avec une Application qui route par nom, gère les erreurs, affiche les listes de commandes et délègue l'exécution à des objets Command.

Cycle de vie d'une commande

Chaque commande traverse exactement quatre méthodes, dans l'ordre. Ne jamais les mélanger :

Codes de retour

La valeur retournée par execute() devient le code de sortie du processus :

// Constantes de la classe Command
Command::SUCCESS  // 0 — tout s'est bien passé
Command::FAILURE  // 1 — erreur métier ou technique
Command::INVALID  // 2 — arguments/options invalides

#[AsCommand]

L'attribut remplace la constante protected static $defaultName héritée :

#[AsCommand(
    name:        'app:users:create',
    description: 'Crée un utilisateur en base',
    aliases:     ['app:user:new'],
    hidden:      false,
)]
final class CreateUserCommand extends Command
{
    // ...
}

Arguments et options

Les arguments sont positionnels et obligatoires ou optionnels — les options commencent par -- et peuvent être des flags, des scalaires ou des tableaux.

Arguments et options sont les deux façons d'alimenter une commande depuis la ligne de commande. Ils ont des sémantiques très différentes — les confondre nuit à l'ergonomie de la CLI.

Arguments — addArgument()

$this->addArgument(
    'username',
    InputArgument::REQUIRED,       // 1 — obligatoire
    'Nom de l\'utilisateur',
    null,                            // valeur par défaut (OPTIONAL seulement)
    ['alice', 'bob']                 // suggestedValues pour l'autocomplétion
);

$this->addArgument('roles', InputArgument::IS_ARRAY);
// Usage : command alice ROLE_USER ROLE_ADMIN
// $input->getArgument('roles') retourne ['ROLE_USER', 'ROLE_ADMIN']

Options — addOption()

$this->addOption(
    'format',                        // nom long : --format
    'f',                             // raccourci : -f
    InputOption::VALUE_REQUIRED,    // 2 — --format=json obligatoire
    'Format de sortie',
    'text',                          // valeur par défaut
    ['text', 'json', 'csv']          // suggestedValues
);

// VALUE_NONE : flag booléen
// --dry-run : $input->getOption('dry-run') === true
// absent   : $input->getOption('dry-run') === false
$this->addOption('dry-run', null, InputOption::VALUE_NONE);

// VALUE_NEGATABLE : --format / --no-format
// --format   : true, --no-format : false, absent : null
$this->addOption('format', null, InputOption::VALUE_NEGATABLE);

OutputInterface et verbosité

OutputInterface est le canal de sortie — il contrôle les niveaux de verbosité et les tags de formatage.

OutputInterface est l'abstraction sur laquelle s'appuient toutes les sorties Console. Elle n'est pas liée au terminal — tu peux la substituer par un BufferedOutput ou un NullOutput sans changer une ligne de code.

Niveaux de verbosité

Cinq niveaux, chacun correspondant à un drapeau CLI. Le niveau minimal déclenche l'affichage de tout le contenu en-dessous de lui :

Écriture conditionnelle

// Méthode directe : passage du niveau en 3e argument de writeln()
$output->writeln('Message verbose', OutputInterface::VERBOSITY_VERBOSE);

// Méthode conditionnelle : garde explicite
if ($output->isVerbose()) {
    $output->writeln('Connexion à la base : ' . $dsn);
}
if ($output->isDebug()) {
    $output->writeln('Requête SQL : ' . $sql);
}

Tags de formatage

La Console interprète des balises XML légères pour colorier la sortie :

$output->writeln('<info>Succès</info>');          // vert
$output->writeln('<comment>Attention</comment>');  // jaune
$output->writeln('<question>Confirmer ?</question>'); // cyan
$output->writeln('<error>Erreur critique</error>');  // blanc sur rouge
$output->writeln('<fg=magenta>Personnalisé</>');
$output->writeln('<fg=white;bg=blue;options=bold>Surligné</>');

SymfonyStyle — la boîte à outils I/O

SymfonyStyle est une façade sur Output qui fournit des blocs visuels structurés — titres, sections, tables, notifications.

SymfonyStyle emballe un InputInterface et un OutputInterface pour offrir une API de haut niveau. Elle impose une cohérence visuelle — espaces, couleurs, encadrés — sans que tu aies à construire les séquences ANSI toi-même.

use Symfony\Component\Console\Style\SymfonyStyle;

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $io = new SymfonyStyle($input, $output);
    $io->title('Importation des utilisateurs');
    // ...
    return Command::SUCCESS;
}

Blocs structurants

$io->title('Import CSV');              // === titre === en jaune
$io->section('Étape 1 : lecture');    // --- section --- en bleu
$io->text('Fichier : import.csv');     // ligne de texte simple
$io->text(['Ligne 1', 'Ligne 2']);   // tableau = plusieurs lignes
$io->listing(['Alice', 'Bob']);      // liste à puces
$io->newLine(2);                       // 2 lignes vides

Notifications

$io->success('42 utilisateurs importés');    // bloc vert [OK]
$io->error('Fichier introuvable');           // bloc rouge [ERROR]
$io->warning('Encodage non UTF-8 détecté');  // bloc orange [WARNING]
$io->note('Aucun doublon trouvé');           // bloc bleu [NOTE]
$io->info('Durée : 2.3s');                  // bloc cyan [INFO]
$io->caution('Opération irréversible !');    // bloc rouge [CAUTION]

// Variantes outline — même couleur, sans fond plein
$io->outlineSuccess('Terminé');
$io->outlineError('Échec partiel');

Tableaux

// Tableau vertical classique
$io->table(
    ['ID', 'Nom', 'Email'],
    [
        [1, 'Alice', 'alice@example.com'],
        [2, 'Bob',   'bob@example.com'],
    ]
);

// Tableau horizontal — headers à gauche, valeurs à droite
$io->horizontalTable(
    ['Symfony', 'PHP', 'Doctrine'],
    [['8.1', '8.4', '3.x']]
);

// Liste de définitions — clé : valeur sur une ligne
$io->definitionList(
    ['Slug' => 'symfony-console'],
    ['Sections' => 10],
    ['Statut' => 'publié'],
);

Questions et interactions

Les helpers de questions permettent d'obtenir des données interactives — avec validation, autocomplétion et gestion des erreurs.

Les commandes interactives posent des questions à l'utilisateur pour collecter des données manquantes. L'objectif est de faire marcher la commande en mode non-interactif (scripts, CI) et de guider l'utilisateur humain lorsqu'il oublie un argument.

Les quatre helpers SymfonyStyle

// Texte libre avec valeur par défaut
$name = $io->ask('Nom d\'utilisateur', 'alice');

// Texte masqué — mot de passe, token
$password = $io->askHidden('Mot de passe');

// Confirmation booléenne
if (!$io->confirm('Êtes-vous sûr ?', false)) {
    return Command::SUCCESS;
}

// Choix dans une liste
$format = $io->choice('Format de sortie', ['json', 'csv', 'text'], 'text');

// Sélection multiple (4e argument = true)
$roles = $io->choice('Rôles', ['ADMIN', 'USER', 'API'], null, true);

Validation et autocomplétion

use Symfony\Component\Console\Question\Question;

$question = new Question('Email : ');
$question->setValidator(function (?string $value): string {
    if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
        throw new \RuntimeException('Email invalide');
    }
    return $value;
});
$question->setMaxAttempts(3);                 // exception après 3 essais
$question->setAutocompleterValues([            // tab-complétion
    'alice@example.com', 'bob@example.com'
]);

$helper = $this->getHelper('question');
$email = $helper->ask($input, $output, $question);

ProgressBar — retour visuel

ProgressBar est le composant de progression visuelle — il affiche des barres, des pourcentages et des estimations de temps.

ProgressBar transforme une boucle silencieuse en retour visuel — sans avoir à calculer les pourcentages ou gérer les séquences d'échappement ANSI. C'est l'un des composants Console les plus utiles pour les commandes longues.

Via SymfonyStyle — la voie rapide

$io->progressStart(100);  // total = 100 éléments
foreach ($items as $item) {
    // traitement…
    $io->progressAdvance();   // avance de 1
}
$io->progressFinish();       // affiche 100% et passe à la ligne

Via ProgressBar directe — le contrôle total

use Symfony\Component\Console\Helper\ProgressBar;

$bar = new ProgressBar($output, 50);
$bar->setFormat('verbose');         // format prédéfini
$bar->setBarCharacter('█');
$bar->setEmptyBarCharacter('░');
$bar->setProgressCharacter('▶');
$bar->setBarWidth(40);
$bar->start();

foreach ($items as $item) {
    $bar->setMessage('Traitement : ' . $item->name);
    // traitement…
    $bar->advance();
}
$bar->finish();

Formats prédéfinis

Placeholders

Un format personnalisé peut utiliser ces placeholders :

$bar->setFormat('[%bar%] %percent:3s%% %current%/%max% %elapsed:6s%/%estimated:-6s% %memory:6s% %message%');

progressIterate() — la voie la plus concise

// Wrap automatique — aucune gestion start/advance/finish
foreach ($io->progressIterate($items, count($items)) as $item) {
    // traitement…
}

Table et rendu structuré

Table génère des tableaux ASCII stylisés — avec des séparateurs, des styles prédéfinis et des titres.

Table génère des tableaux alignés automatiquement dans le terminal. Elle gère les largeurs de colonnes, les séparateurs et plusieurs styles visuels.

Usage de base

use Symfony\Component\Console\Helper\Table;
use Symfony\Component\Console\Helper\TableSeparator;

$table = new Table($output);
$table
    ->setHeaderTitle('Utilisateurs')
    ->setHeaders(['ID', 'Nom', 'Rôle'])
    ->setRows([
        [1, 'Alice', 'ADMIN'],
        [2, 'Bob',   'USER'],
        new TableSeparator(),
        [3, 'Carol', 'API'],
    ])
    ->setFooterTitle('3 utilisateurs')
    ->render();

Styles visuels

$table->setStyle('box');         // ┌─┬─┐ / │ │ │ / └─┴─┘
$table->setStyle('box-double');  // ╔═╦═╗ / ║ ║ ║ / ╚═╩═╝
$table->setStyle('compact');     // sans bordures externes
$table->setStyle('default');     // +---+---+ (ASCII pur)

Contrôle des largeurs

// Largeur fixe d'une colonne (index 0-based)
$table->setColumnWidth(1, 30);     // colonne 1 = 30 chars

// Largeur maximale — tronque avec "…" si dépassée
$table->setColumnMaxWidth(2, 20);

Le dispatch de l'Application

run(), doRun() et surtout find() transforment le nom que tu tapes en une commande précise — abréviation par segments, alias et détection d'ambiguïté.

Quand tu tapes bin/console app:us:cr, aucune de tes commandes ne s'exécute directement. La saisie traverse d'abord un routeur : l'Application transforme le texte que tu as tapé en un objet Command précis, avant de lui passer la main.

find() — la résolution de nom

C'est le cœur du routeur. Il tente les stratégies dans l'ordre, et s'arrête à la première qui donne un résultat certain :

// Simplifié depuis Application::find()
// 1. Correspondance exacte (nom OU alias déjà enregistré)
if ($this->has($name)) {
    return $this->get($name);
}

// 2. Abréviation : chaque segment séparé par ":" peut être tronqué
$expr = implode('[^:]*:', array_map('preg_quote', explode(':', $name))) . '[^:]*';
$commands = preg_grep('{^' . $expr . '}', $allCommands);

Concrètement, app:us:cr devient la regex app[^:]*:us[^:]*:cr[^:]*. Elle accepte application:users:create — chaque segment est un préfixe, les deux-points sont les frontières. C'est pour ça que tu peux taper c:c pour cache:clear, mais jamais sauter un segment.

Les trois issues possibles

Avant de trancher l'ambiguïté, find() fait deux nettoyages : il retire les alias qui pointent vers une commande déjà listée, puis vérifie si tous les candidats restants sont en réalité des alias d'une seule et même commande — auquel cas il n'y a pas d'ambiguïté. Les commandes isHidden() sont aussi écartées des suggestions.

doRunCommand() — le relais

Une fois la commande trouvée, doRunCommand() ne se contente pas d'appeler $command->run(). S'il n'y a pas d'EventDispatcher, c'est effectivement tout ce qu'il fait. Mais dès qu'un dispatcher est présent (le cas par défaut en full-stack), il enveloppe l'exécution dans un cycle d'événements et de gestion de signaux — c'est l'objet des deux sections suivantes.

Les événements Console

COMMAND, ERROR et TERMINATE ceinturent chaque exécution — de quoi désactiver, rattraper ou nettoyer une commande sans toucher à son code.

Autour de chaque exécution, quand un EventDispatcher est branché sur l'application (le cas par défaut en full-stack), Console déclenche une petite chorégraphie d'événements. Ils te permettent de journaliser, mesurer, désactiver ou rattraper une commande sans jamais toucher son code.

L'ordre garanti

COMMAND — désactiver avant de lancer

L'événement COMMAND est émis après que les arguments et options ont été liés à la commande : tes listeners voient donc déjà les entrées. Un listener peut appeler disableCommand() ; doRunCommand() vérifie ensuite commandShouldRun() et, si c'est faux, saute execute() en renvoyant le code spécial 113 :

use Symfony\Component\Console\ConsoleEvents;
use Symfony\Component\Console\Event\ConsoleCommandEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: ConsoleEvents::COMMAND)]
final class MaintenanceModeListener
{
    public function __invoke(ConsoleCommandEvent $event): void
    {
        if ($this->maintenance->isOn() && $event->getCommand()?->getName() === 'app:import') {
            $event->getOutput()->writeln('<comment>Import gelé pendant la maintenance.</comment>');
            $event->disableCommand(); // execute() ne sera pas appelée
        }
    }
}

ERROR — intercepter et neutraliser

Si execute() (ou un listener COMMAND) lève une exception, ERROR est déclenché avec l'exception dans l'événement. Un listener peut la remplacer (setError()) ou la neutraliser en forçant un code de sortie — si ce code vaut 0, l'exception est oubliée et n'est pas relancée :

#[AsEventListener(event: ConsoleEvents::ERROR)]
public function onError(ConsoleErrorEvent $event): void
{
    $this->logger->error($event->getError()->getMessage());
    // Transforme un timeout réseau en code 75 (EX_TEMPFAIL) sans stacktrace
    if ($event->getError() instanceof TransportException) {
        $event->setExitCode(75);
    }
}

TERMINATE — le nettoyage inconditionnel

TERMINATE est le finally du cycle : il part toujours, succès ou échec, et c'est le dernier à pouvoir réécrire le code de sortie via setExitCode(). Son getInterruptingSignal() te dit même si l'arrêt vient d'un signal Unix (voir la section suivante). C'est l'endroit idéal pour fermer une connexion, purger un buffer ou pousser une métrique de durée.

Réagir aux signaux Unix

SignalableCommandInterface et l'événement SIGNAL permettent d'arrêter proprement un worker sur Ctrl-C ou SIGTERM, en finissant la tâche en cours.

Ctrl-C au milieu d'un import de deux millions de lignes : soit tu coupes brutalement et laisses une transaction à moitié écrite, soit tu finis proprement la ligne en cours puis rends la main. Console offre les deux mécanismes pour ça — au niveau de la commande, ou au niveau de l'application.

use Symfony\Component\Console\Command\SignalableCommandInterface;

final class ImportCommand extends Command implements SignalableCommandInterface
{
    private bool $shouldStop = false;

    public function getSubscribedSignals(): array
    {
        return [SIGINT, SIGTERM]; // Ctrl-C et arrêt propre
    }

    public function handleSignal(int $signal, int|false $previousExitCode = 0): int|false
    {
        $this->shouldStop = true;

        return false; // false = ne quitte pas maintenant, laisse execute() finir
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        foreach ($this->rows() as $row) {
            if ($this->shouldStop) {
                break; // on sort de la boucle après la ligne en cours
            }
            $this->process($row);
        }

        return Command::SUCCESS;
    }
}

ConsoleEvents::SIGNAL — au niveau application

Il existe une seconde voie, découplée de toute commande : l'événement SIGNAL. Quand un dispatcher est présent, l'application écoute par défaut un jeu de signaux et émet un ConsoleSignalEvent à leur réception. Utile pour une préoccupation globale — vider un cache, flusher des métriques — quelle que soit la commande en cours :

// Signaux écoutés par défaut quand un dispatcher est branché :
[SIGINT, SIGQUIT, SIGTERM, SIGUSR1, SIGUSR2, SIGALRM]
// Ajustable via Application::setSignalsToDispatchEvent(...)

#[AsEventListener(event: ConsoleEvents::SIGNAL)]
public function onSignal(ConsoleSignalEvent $event): void
{
    $this->metrics->flush();
    $event->abortExit(); // empêche la sortie automatique, on laisse tourner
}

Sous le capot — SignalRegistry

Le mécanisme repose sur l'extension pcntl. À la construction, l'application active pcntl_async_signals(true) via un SignalRegistry : les signaux sont livrés de façon asynchrone, sans avoir à parsemer ton code d'appels à pcntl_signal_dispatch(). Le registre empile les gestionnaires existants avant l'exécution et les restaure après, pour ne pas écraser ceux d'un éventuel processus parent.

Autocomplétion et LazyCommand

Console supporte l'autocomplétion native du shell — et LazyCommand diffère l'instanciation pour des applications avec beaucoup de commandes.

Deux fonctionnalités avancées qui améliorent l'ergonomie et les performances des CLI complexes : l'autocomplétion native du shell, et LazyCommand qui diffère l'instanciation des commandes jusqu'à leur invocation.

Autocomplétion — complete()

Pour qu'une commande propose des suggestions au shell (bash/zsh/fish), implémente la méthode complete(). Elle est appelée par la sous-commande interne _complete :

use Symfony\Component\Console\Completion\CompletionInput;
use Symfony\Component\Console\Completion\CompletionSuggestions;

public function complete(
    CompletionInput $input,
    CompletionSuggestions $suggestions
): void {
    // Suggestion pour un argument
    if ($input->mustSuggestArgumentValuesFor('username')) {
        $suggestions->suggestValues(['alice', 'bob', 'carol']);
        return;
    }

    // Suggestion pour une option
    if ($input->mustSuggestOptionValuesFor('format')) {
        $suggestions->suggestValues(['json', 'csv', 'text']);
        return;
    }

    // Suggestion d'options supplémentaires
    if ($input->getCompletionType() === CompletionInput::TYPE_OPTION_NAME) {
        $suggestions->suggestOptions($this->getDefinition()->getOptions());
    }
}

LazyCommand — instanciation différée

Dans une application avec des centaines de commandes, instancier chaque Command (et donc ses dépendances) au démarrage est coûteux. LazyCommand résout ce problème :

use Symfony\Component\Console\Command\LazyCommand;

// Dans l'Application ou un CompilerPass :
$application->add(new LazyCommand(
    name:           'app:heavy:process',
    aliases:        ['app:process'],
    description:    'Traitement lourd avec beaucoup de dépendances',
    isHidden:       false,
    commandFactory: fn() => new HeavyProcessCommand($dep1, $dep2),
));

Sous le capot — la découverte des commandes taguées

Comment le framework connaît-il le nom et la description de centaines de commandes sans en instancier une seule au démarrage ? Grâce à un compiler pass qui travaille à la compilation du conteneur, bien avant le moindre bin/console.

En full-stack, toute classe étendant Command reçoit automatiquement le tag console.command (autoconfiguration). Le AddConsoleCommandPass parcourt alors ces services et, par réflexion seule, lit l'attribut #[AsCommand] pour en extraire nom, alias, description et état caché — sans exécuter le constructeur :

// Ce que construit AddConsoleCommandPass, schématiquement :
$lazyCommandMap = [
    'app:users:create' => 'App\Command\CreateUserCommand', // nom  => id de service
    'app:user:new'    => 'App\Command\CreateUserCommand', // alias => même id
];

// Chaque service est enveloppé dans un LazyCommand (.id.lazy)
// puis exposé via un ContainerCommandLoader :
$loader = new ContainerCommandLoader($serviceLocator, $lazyCommandMap);
$application->setCommandLoader($loader);

La boucle se ferme avec find() (vu dans la section Dispatch) : celui-ci interroge commandLoader->getNames() pour lister et router, et n'appelle get() que sur la commande gagnante. Résultat : bin/console list affiche des centaines de commandes en lisant uniquement des métadonnées, sans démarrer une seule dépendance.

Tester ses commandes

Symfony fournit CommandTester pour tester les commandes sans instancier l'Application — avec simulation d'inputs et capture d'output.

Tester une commande Console ne doit pas nécessiter de lancer un processus — CommandTester capture la sortie et simule les entrées en mémoire, rendant les tests rapides et isolés.

Structure d'un test

use Symfony\Bundle\FrameworkBundle\Console\Application;
use Symfony\Component\Console\Tester\CommandTester;

class CreateUserCommandTest extends KernelTestCase
{
    public function testExecute(): void
    {
        // Instancier la commande avec ses dépendances mockées
        $command = new CreateUserCommand(
            $this->createMock(UserRepository::class)
        );

        $tester = new CommandTester($command);

        // Exécuter avec des arguments et options
        $tester->execute([
            'username' => 'alice',        // argument
            '--format' => 'json',          // option
            '--dry-run' => true,           // flag
        ], [
            'decorated' => false,           // désactive les couleurs ANSI
        ]);

        // Assertions
        $tester->assertCommandIsSuccessful();
        $this->assertStringContainsString('alice', $tester->getDisplay());
    }
}

Tester les questions interactives

// setInputs() simule les réponses clavier dans l'ordre
$tester->setInputs(['alice', 'motdepasse', 'yes']);
$tester->execute([]);

API complète de CommandTester

Synthèse — guide de choix et anti-patterns

Le guide de choix et les anti-patterns de Console Symfony.

Après neuf sections, voici les guides de décision qui s'appliquent à la construction d'une interface CLI robuste avec Symfony Console.

Guide de choix : argument ou option ?

Guide de choix : quelle question poser ?

Guide de choix : ProgressBar

Récapitulatif des modes

4 anti-patterns à éviter