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);

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),
));

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