winzik/docs/ide/fr/command-wizards.md
2026-11-16 07:23:56 +01:00

69 lines
5.2 KiB
Markdown

# Assistants de commandes
Deux assistants écrivent une commande de console ou une tâche à partir d'un formulaire, au lieu de taper le code répétitif : l'assistant
**commande Symfony** (`src/Command/`) et l'assistant **tâche Castor** (`castor.php` ou `.castor/`). Les deux relisent aussi une commande
ou une tâche existante dans le formulaire pour la modifier, et peuvent lancer ce qu'ils décrivent depuis leur propre formulaire.
## Commande Symfony
Ouvrez-le par **Outils > New Symfony Command…**, par le **+** de la fenêtre [Console Symfony](symfony-console.md) ou, pour modifier une
commande existante, par **Edit in the wizard** sur elle dans cette fenêtre.
![L'assistant de commande Symfony : le formulaire à gauche, le code qui sera écrit à droite](../images/command-wizard-symfony.png)
Le formulaire est à gauche, le **nouveau code** à droite, mis à jour pendant la saisie.
- **Commande** : nom (`app:monthly-report`), classe, description, alias, *Hidden* (masquée), aide, et le **style** : *Attributes*
(Symfony 7.3+ : `#[AsCommand]` sur une classe avec `__invoke()`, paramètres marqués `#[Argument]` / `#[Option]`) ou *Classic*
(`configure()` avec `addArgument()` / `addOption()`, et `execute()`). Le choix par défaut suit la version de `symfony/console` dans
`composer.lock` ; le formulaire dit laquelle il a trouvée.
- **Arguments** : nom, mode (obligatoire / optionnel), type, *Several* (un tableau), valeur par défaut, description.
- **Options** : nom, raccourci, mode (drapeau, valeur obligatoire, valeur optionnelle, plusieurs valeurs, `--x / --no-x`), type, défaut,
description.
- **Services** : classes ou interfaces trouvées par l'index PHP, injectées dans le constructeur en `private readonly`.
- **Corps** : cliquez les étapes de la palette pour les ajouter dans l'ordre : titre SymfonyStyle, section, texte, question, confirmation,
choix, barre de progression, tableau, messages succès / note / avertissement / erreur, lignes de PHP libres. Choisissez ensuite ce que
la commande renvoie (`Command::SUCCESS`, `FAILURE` ou `INVALID`).
Le fichier est écrit dans `src/Command/<Classe>.php`, dans l'espace de noms que la section `psr-4` de `composer.json` donne.
## Tâche Castor
Ouvrez-la par **Outils > New Castor Task…**, par le menu de la fenêtre [Scripts](scripts.md) ou par **Edit in the Wizard…** sur une
tâche Castor.
![L'assistant de tâche Castor](../images/command-wizard-castor.png)
- **Where** (où) : le *type* et l'endroit où c'est écrit : `castor.php` (créé s'il manque) ou un fichier de `.castor/` (le fichier racine
reçoit alors son `import(__DIR__ . '/.castor/x.php')`). Les lignes `use` sont ajoutées par ordre alphabétique.
- **Tâche** (`#[AsTask]`) : nom, espace de noms, description, alias, *Default task*. Un nom de fonction que PHP possède déjà (`reset`,
`copy`…) est évité : `db:reset` devient `dbReset()`.
- **Arguments et options** (`#[AsArgument]` / `#[AsOption]`) : mode, raccourci, type, défaut, description. L'attribut est omis quand
Castor devine la même chose.
- **Contexte** (`#[AsContext]`) : dossier de travail, environnement, données, TTY, délai, échec permis, silencieux. **Écouteur**
(`#[AsListener]`) : une fonction appelée sur un événement de Castor.
- **Étapes du corps** : `run()` et `capture()` avec un contexte (dossier de travail, environnement, TTY, délai, échec permis), sorties et
questions `io()`, opérations `fs()`, `http_request()`, `watch()`, `notify()`, `variable()`, lignes de PHP.
## Écrire, modifier et lancer
- Chaque changement est montré **sous forme de diff** d'abord, avec les fichiers touchés (un nouveau fichier `.castor/` et le fichier
racine qui l'importe), et n'est écrit que si vous cliquez **Write the File**. Si un fichier a changé depuis l'aperçu, rien n'est
écrit : rouvrez l'assistant.
- **Modifier une commande ou une tâche existante** la relit dans le formulaire (les deux styles Symfony, et les anciennes formes
`setDescription()` / `'nom|alias'`). Seul ce que vous avez changé est réécrit : les nouveaux arguments, options et services sont
insérés dans la présentation propre à la liste, ceux retirés disparaissent, et tous les autres octets du fichier restent tels quels.
La variable d'un argument renommé suit dans le corps. **Le corps n'est jamais touché par une modification.**
- **Run…** ouvre le *formulaire de lancement* : un champ par argument, une case ou un champ par option, et la ligne de commande qui en
résulte (avec un bouton de copie). Une commande Symfony se lance par le lanceur de la fenêtre Console (un onglet Terminal, ou
**Run here** quand elle ne pose pas de questions) ; une tâche Castor par la fenêtre Scripts. **Run with Arguments…** sur une tâche
Castor ouvre le même formulaire.
![Le formulaire de lancement d'une tâche Castor](../images/command-wizard-run.png)
## Limites
- Le corps d'une commande ou d'une tâche existante n'est **pas** relu en étapes : l'assistant le garde tel quel.
- Les services s'ajoutent par une modification ; pour en retirer un, modifiez la classe dans l'éditeur.
- Un contexte ou un écouteur Castor est créé par l'assistant, pas modifié par lui.
- `help:` dans `#[AsCommand]` demande Symfony 7.3 ; le style classique utilise `setHelp()`.