66 lines
4.6 KiB
Markdown
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 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.
|
|
|
|

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

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