[Console] Document invokable command #20932

yceruto · 2025-05-01T15:57:03Z

Closes #20553

Make invokable commands first-class citizen
Move old command definition to a separate section

Pending docs to be updated:

components/console/console_arguments.rst (full refactoring required)
components/console/helpers/questionhelper.rst (full refactoring required)
console/input.rst (full refactoring required)
console.rst (full refactoring required)

alamirault

I like the harmonization of some command names 👍

logging/monolog_console.rst

components/console/helpers/tree.rst

console/style.rst

components/console/changing_default_command.rst

logging/monolog_console.rst

components/console/events.rst

console.rst

OskarStark · 2025-05-05T17:10:10Z

console/calling_commands.rst

+    #[AsCommand(name: 'app:create-user')]
+    class CreateUserCommand


maybe we should make all these changes with the #AsCommand attribute in a separate PR to avoid growing this PR?

I’d actually prefer to keep all these related changes in a single PR, since they’re closely tied together. It helps keep the context in one place and makes it easier to review everything as a whole.

In any case, we can go ahead and merge this one, then open a new PR for the remaining updates.

yceruto · 2025-05-05T18:05:43Z

Thanks @alamirault and @OskarStark for your review 🙏

I’m actively looking for someone to help me refactor console.rst, as I’m running out of free-time before the final release.

components/console/helpers/cursor.rst

94noni · 2025-05-05T19:14:06Z

components/console/helpers/questionhelper.rst

-        // ...
-
-        public function execute(InputInterface $input, OutputInterface $output): int
+        public function __invoke(InputInterface $input, OutputInterface $output): int
        {
            $helper = $this->getHelper('question');


this wont work isnt it ?
or are those console helper injectable in some ways ?

Good catch! Yes, there is a way, but I’m not sure if it’s simpler to extend Command or to get the helper via:

public function __invoke(InputInterface $input, OutputInterface $output, Application $application): int { $helper = $application->getHelperSet()->get('question'); // ... }

Anyway, this all looks old-fashioned, because SymfonyStyle can do it better. There’s even a note right at the beginning:

.. note:: As an alternative, consider using the :ref:`SymfonyStyle <symfony-style-questions>` to ask questions.

IMO, it’s not just an alternative, but the simplest way to ask questions from now on:

public function __invoke(SymfonyStyle $io): int { $answer = $io->ask(...); }

I think we should do the same here as with invokable commands: start with the simpler approach (SymfonyStyle), then mention alternatives for custom needs. wdyt @symfony/docs ?

for documentation I agree yes, basic usage then more advance 👍🏻

a question just: cant we imagine those helper as console service as injectable in the invoke method ? (can open an dedicated issue for later :))

94noni · 2025-05-05T19:21:49Z

Pending docs to be updated:

I would also add https://symfony.com/doc/current/console/input.html, wdyt @yceruto ?
I can help on this in a separate unitary PR if its ok

yceruto · 2025-05-05T20:46:06Z

Thanks, Antoine! Sure, go for it.

Here we're discussing input related topics symfony/symfony#59602

javiereguiluz

Yonel, thanks a lot for this massive contribution 🙇

I agree with what you said here:

we can go ahead and merge this one, then open a new PR for the remaining updates

I'll wait a bit to read more opinions, but that's the plan I'd like to follow. Thanks!

wouterj

I agree with doing the work in steps, but I think the order should be swapped around.

We can't update all examples across the documentation to use features that we didn't document properly. Imho, console/input.rst has to be updated before we can start using #[Option]/#[Argument] in the documentation.
But it would be perfectly fine if all articles in the docs still have outdated (too complex) examples, but the main guides are updated to document both the simple + advanced way.

We must also be careful about updating an example without updating the context it is placed in (I tried to comment on those cases whenever I saw this).

wouterj · 2025-05-10T17:15:18Z

console.rst

+leverage advanced features like lifecycle hooks: :method:`Symfony\\Component\\Console\\Command\\Command::initialize`,
+:method:`Symfony\\Component\\Console\\Command\\Command::interact`, and built-in helpers.


Suggested change

leverage advanced features like lifecycle hooks: :method:`Symfony\\Component\\Console\\Command\\Command::initialize`,

:method:`Symfony\\Component\\Console\\Command\\Command::interact`, and built-in helpers.

leverage advanced features like lifecycle hooks (e.g. :method:`Symfony\\Component\\Console\\Command\\Command::initialize` and

:method:`Symfony\\Component\\Console\\Command\\Command::interact`) and built-in helpers.

wouterj · 2025-05-10T17:20:55Z

console.rst

+Additionally, you can extend the :class:`Symfony\\Component\\Console\\Command\\Command` class to
+leverage advanced features like lifecycle hooks: :method:`Symfony\\Component\\Console\\Command\\Command::initialize`,
+:method:`Symfony\\Component\\Console\\Command\\Command::interact`, and built-in helpers.
+
 Configuring the Command


This whole section needs updating, the text currently no longer matches the updated code example.

I think we can remove it completely, and instead merge it with the previous section. Something like

You can also use ``#[AsCommand]`` to add a description and longer help text for the command:: // src/Command/CreateUserCommand.php #[AsCommand( name: 'app:create-user', description: 'Creates a new user.', // the command description shown when running "php bin/console list" help: 'This command allows you to create a user...', // the command help shown when running the command with the "--help" option )] class CreateUserCommand { public function __invoke(): int { // ... } } Additionally, you can extend the :class:`Symfony\\Component\\Console\\Command\\Command` class to leverage advanced features like lifecycle hooks (e.g. :method:`Symfony\\Component\\Console\\Command\\Command::initialize`, :method:`Symfony\\Component\\Console\\Command\\Command::interact`) and built-in helpers.

wouterj · 2025-05-10T17:22:42Z

console.rst

-                // the command help shown when running the command with the "--help" option
-                ->setHelp('This command allows you to create a user...')
-            ;
+            // ...
        }
    }



The next section ("Registering the Command") also needs rework, the document now only shows the #[AsCommand] examples, so "You can register the command by adding the AsCommand attribute to it:" is out of place now.

However, we need to document the final paragraph ("If you can't use PHP attributes, register the command as a service [...]") somewhere in this article I think.

wouterj · 2025-05-10T17:23:48Z

console/calling_commands.rst

@@ -18,16 +18,15 @@ the returned code from the command (return value from command ``execute()``
 method)::


This paragraph needs rework, it talks about the execute() method which no longer exists in the example.

wouterj · 2025-05-10T17:24:24Z

console/calling_commands.rst

@@ -18,16 +18,15 @@ the returned code from the command (return value from command ``execute()``
 method)::

    // ...
+    use Symfony\Component\Console\Attribute\AsCommand;
    use Symfony\Component\Console\Command;


Suggested change

use Symfony\Component\Console\Command;

wouterj · 2025-05-10T17:25:31Z

console/commands_as_services.rst

@@ -70,7 +59,7 @@ To make your command lazily loaded, either define its name using the PHP
    // ...

    #[AsCommand(name: 'app:sunshine')]
-    class SunshineCommand extends Command
+    class SunshineCommand


We reuse this command in the example below to configure it using the console.command tag. Is this tag compatible with non-Command classes?

wouterj · 2025-05-10T17:27:39Z

console/style.rst

-class and pass the ``$input`` and ``$output`` variables as its arguments. Then,
-you can start using any of its helpers, such as ``title()``, which displays the
-title of the command::
+In your `__invoke` method, add an argument of type :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle`.


Suggested change

In your `__invoke` method, add an argument of type :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle`.

In your ``__invoke()`` method, add an argument of type :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle`.

wouterj · 2025-05-10T17:32:02Z

console/verbosity.rst

-        // ...
-
-        public function execute(InputInterface $input, OutputInterface $output): int
+        public function __invoke(OutputInterface $output, #[Argument] string $username, #[Argument] string $password): int


This PR doesn't update https://symfony.com/doc/current/console/input.html (not sure if that is intentional). This means that we never documented #[Argument] or #[Option].

I don't think it's a good idea to update other examples with these attributes as long as we don't document the attributes themselves.

carsonbot added Status: Needs Review Console labels May 1, 2025

carsonbot added this to the 7.3 milestone May 1, 2025

yceruto mentioned this pull request May 1, 2025

[Console] Add support for invokable commands and input attributes #20553

Open

yceruto force-pushed the invokable_command branch 2 times, most recently from 42c2a79 to 3d9b930 Compare May 1, 2025 16:31

Document invokable command

a59a80c

yceruto force-pushed the invokable_command branch from 3d9b930 to a59a80c Compare May 1, 2025 16:40

alamirault reviewed May 2, 2025

View reviewed changes

Antoine's Review

4a417f1

OskarStark reviewed May 5, 2025

View reviewed changes

components/console/events.rst Outdated Show resolved Hide resolved

OskarStark reviewed May 5, 2025

View reviewed changes

components/console/events.rst Outdated Show resolved Hide resolved

OskarStark reviewed May 5, 2025

View reviewed changes

console.rst Outdated Show resolved Hide resolved

OskarStark reviewed May 5, 2025

View reviewed changes

Oskar's Review

236dd82

94noni reviewed May 5, 2025

View reviewed changes

components/console/helpers/cursor.rst Outdated Show resolved Hide resolved

94noni reviewed May 5, 2025

View reviewed changes

Antoine's Review

1a9a5d7

javiereguiluz approved these changes May 9, 2025

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels May 9, 2025

wouterj requested changes May 10, 2025

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Reviewed labels May 10, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Console] Document invokable command #20932

[Console] Document invokable command #20932

yceruto commented May 1, 2025 •

edited

Loading

alamirault left a comment •

edited

Loading

OskarStark May 5, 2025

yceruto May 5, 2025

yceruto commented May 5, 2025

94noni May 5, 2025 •

edited

Loading

yceruto May 5, 2025 •

edited

Loading

yceruto May 5, 2025

94noni May 6, 2025

94noni commented May 5, 2025 •

edited

Loading

yceruto commented May 5, 2025

javiereguiluz left a comment

wouterj left a comment •

edited

Loading

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

wouterj May 10, 2025

		#[AsCommand(name: 'app:create-user')]
		class CreateUserCommand

		leverage advanced features like lifecycle hooks: :method:`Symfony\\Component\\Console\\Command\\Command::initialize`,
		:method:`Symfony\\Component\\Console\\Command\\Command::interact`, and built-in helpers.

		@@ -18,16 +18,15 @@ the returned code from the command (return value from command ``execute()``
		method)::

	In your `__invoke` method, add an argument of type :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle`.
	In your ``__invoke()`` method, add an argument of type :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle`.

[Console] Document invokable command #20932

Are you sure you want to change the base?

[Console] Document invokable command #20932

Conversation

yceruto commented May 1, 2025 • edited Loading

alamirault left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yceruto commented May 5, 2025

94noni May 5, 2025 • edited Loading

Choose a reason for hiding this comment

yceruto May 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

94noni commented May 5, 2025 • edited Loading

yceruto commented May 5, 2025

javiereguiluz left a comment

Choose a reason for hiding this comment

wouterj left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yceruto commented May 1, 2025 •

edited

Loading

alamirault left a comment •

edited

Loading

94noni May 5, 2025 •

edited

Loading

yceruto May 5, 2025 •

edited

Loading

94noni commented May 5, 2025 •

edited

Loading

wouterj left a comment •

edited

Loading