69 lines
5.2 KiB
Markdown
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.
|
|
|
|

|
|
|
|
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.
|
|
|
|

|
|
|
|
- **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.
|
|
|
|

|
|
|
|
## 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()`.
|