DE

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

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 window, or with Edit in the Wizard… on a Castor task.

The Castor task wizard

  • 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

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