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

66 lines
4.6 KiB
Markdown

# Command wizards
Two wizards write a console command or a task from a form, instead of typing the boilerplate: the **Symfony command** wizard
(`src/Command/`) and the **Castor task** wizard (`castor.php` or `.castor/`). Both also read an existing command or task back into
the form to edit it, and both can run what they describe from a form of their own.
## Symfony command
Open it from **Tools > New Symfony Command…**, from the **+** of the [Symfony console](symfony-console.md) window, or, to change a
command that exists, with **Edit in the wizard** on it in that window.
![The Symfony command wizard: the form on the left, the code that will be written on the right](images/command-wizard-symfony.png)
The form is on the left, the **new code** on the right, updated as you type.
- **Command**: name (`app:monthly-report`), class, description, aliases, *Hidden*, help text, and the **style**:
*Attributes* (Symfony 7.3+: `#[AsCommand]` on a class with `__invoke()`, parameters marked `#[Argument]` / `#[Option]`) or
*Classic* (`configure()` with `addArgument()` / `addOption()`, and `execute()`). The default follows the version of
`symfony/console` in `composer.lock`; the form says which one it found.
- **Arguments**: name, mode (required / optional), type, *Several* (an array), default value, description.
- **Options**: name, shortcut, mode (flag, value required, value optional, several values, `--x / --no-x`), type, default, description.
- **Services**: classes or interfaces found by the PHP index, injected in the constructor as `private readonly`.
- **Body**: click the steps of the palette to add them in order: SymfonyStyle title, section, text, ask, confirm, choice, progress bar,
table, success / note / warning / error messages, free lines of PHP. Then choose what the command returns
(`Command::SUCCESS`, `FAILURE` or `INVALID`).
The file is written to `src/Command/<Class>.php`, in the namespace that the `psr-4` section of `composer.json` gives.
## Castor task
Open it from **Tools > New Castor Task…**, from the menu of the [Scripts](scripts.md) window, or with **Edit in the Wizard…** on a
Castor task.
![The Castor task wizard](images/command-wizard-castor.png)
- **Where**: the *kind* and where it is written: `castor.php` (created when missing) or a file of `.castor/` (the root file then gets
its `import(__DIR__ . '/.castor/x.php')`). The `use` lines are added in alphabetical order.
- **Task** (`#[AsTask]`): name, namespace, description, aliases, *Default task*. A function name that PHP already has (`reset`,
`copy`…) is avoided: `db:reset` becomes `dbReset()`.
- **Arguments and options** (`#[AsArgument]` / `#[AsOption]`): mode, shortcut, type, default, description. The attribute is left out
when Castor guesses the same thing.
- **Context** (`#[AsContext]`): working folder, environment, data, TTY, timeout, allow failure, quiet. **Listener**
(`#[AsListener]`): a function called on a Castor event.
- **Body steps**: `run()` and `capture()` with a context (working directory, environment, TTY, timeout, allow failure), `io()`
output and questions, `fs()` operations, `http_request()`, `watch()`, `notify()`, `variable()`, lines of PHP.
## Writing, editing and running
- Every change is shown **as a diff** first, with the files it touches (a new `.castor/` file and the root file that imports it), and
written only when you click **Write the File**. If a file changed since the preview, nothing is written: open the wizard again.
- **Editing an existing command or task** reads it back into the form (both Symfony styles, and the older `setDescription()` /
`'name|alias'` forms). Only what you changed is rewritten: new arguments, options and services are inserted in the list's own
layout, removed ones go away, and every other byte of the file stays as it was. A renamed argument's variable follows in the body.
**The body is never touched by an edit.**
- **Run…** opens the *run form*: a field per argument, a checkbox or field per option, and the command line it makes (with a copy
button). A Symfony command runs through the Console window's runner (a Terminal tab, or **Run here** when it asks nothing); a Castor
task runs through the Scripts window. **Run with Arguments…** on a Castor task opens the same form.
![The run form of a Castor task](images/command-wizard-run.png)
## Limits
- The body of an existing command or task is **not** read back into steps: the wizard keeps it as it is.
- Services are added by an edit; to remove one, edit the class in the editor.
- A Castor context or listener is created by the wizard, not edited by it.
- `help:` inside `#[AsCommand]` needs Symfony 7.3; the classic style uses `setHelp()`.