[Console] Allow Usages to be specified via #[AsCommand]

weitzman · chalasr · commit e4d2645ee1d8 · 2025-06-13T14:15:18.000+02:00
diff --git a/src/Symfony/Component/Console/Application.php b/src/Symfony/Component/Console/Application.php
@@ -564,6 +564,10 @@ public function addCommand(callable|Command $command): ?Command
                 ->setDescription($attribute->description ?? '')
                 ->setHelp($attribute->help ?? '')
                 ->setCode($command);
+
+            foreach ($attribute->usages as $usage) {
+                $command->addUsage($usage);
+            }
         }
 
         $command->setApplication($this);
diff --git a/src/Symfony/Component/Console/Attribute/AsCommand.php b/src/Symfony/Component/Console/Attribute/AsCommand.php
@@ -25,13 +25,15 @@ class AsCommand
      * @param string[]    $aliases     The list of aliases of the command. The command will be executed when using one of them (i.e. "cache:clean")
      * @param bool        $hidden      If true, the command won't be shown when listing all the available commands, but it can still be run as any other command
      * @param string|null $help        The help content of the command, displayed with the help page
+     * @param string[]    $usages      The list of usage examples, displayed with the help page
      */
     public function __construct(
         public string $name,
         public ?string $description = null,
         array $aliases = [],
         bool $hidden = false,
         public ?string $help = null,
+        public array $usages = [],
     ) {
         if (!$hidden && !$aliases) {
             return;
diff --git a/src/Symfony/Component/Console/CHANGELOG.md b/src/Symfony/Component/Console/CHANGELOG.md
@@ -8,6 +8,7 @@ CHANGELOG
  * Introduce `Symfony\Component\Console\Application::addCommand()` to simplify using invokable commands when the component is used standalone
  * Deprecate `Symfony\Component\Console\Application::add()` in favor of `Symfony\Component\Console\Application::addCommand()`
  * Add `BackedEnum` support with `#[Argument]` and `#[Option]` inputs in invokable commands
+ * Allow Usages to be specified via #[AsCommand] attribute.
 
 7.3
 ---
diff --git a/src/Symfony/Component/Console/Command/Command.php b/src/Symfony/Component/Console/Command/Command.php
@@ -134,6 +134,10 @@ public function __construct(?string $name = null)
             $this->setHelp($attribute?->help ?? '');
         }
 
+        foreach ($attribute?->usages ?? [] as $usage) {
+            $this->addUsage($usage);
+        }
+
         if (\is_callable($this) && (new \ReflectionMethod($this, 'execute'))->getDeclaringClass()->name === self::class) {
             $this->code = new InvokableCommand($this, $this(...));
         }
diff --git a/src/Symfony/Component/Console/DependencyInjection/AddConsoleCommandPass.php b/src/Symfony/Component/Console/DependencyInjection/AddConsoleCommandPass.php
@@ -91,6 +91,7 @@ public function process(ContainerBuilder $container): void
 
             $description = $tags[0]['description'] ?? null;
             $help = $tags[0]['help'] ?? null;
+            $usages = $tags[0]['usages'] ?? null;
 
             unset($tags[0]);
             $lazyCommandMap[$commandName] = $id;
@@ -108,6 +109,7 @@ public function process(ContainerBuilder $container): void
 
                 $description ??= $tag['description'] ?? null;
                 $help ??= $tag['help'] ?? null;
+                $usages ??= $tag['usages'] ?? null;
             }
 
             $definition->addMethodCall('setName', [$commandName]);
@@ -124,6 +126,12 @@ public function process(ContainerBuilder $container): void
                 $definition->addMethodCall('setHelp', [str_replace('%', '%%', $help)]);
             }
 
+            if ($usages) {
+                foreach ($usages as $usage) {
+                    $definition->addMethodCall('addUsage', [$usage]);
+                }
+            }
+
             if (!$description) {
                 if (Command::class !== (new \ReflectionMethod($class, 'getDefaultDescription'))->class) {
                     trigger_deprecation('symfony/console', '7.3', 'Overriding "Command::getDefaultDescription()" in "%s" is deprecated and will be removed in Symfony 8.0, use the #[AsCommand] attribute instead.', $class);
diff --git a/src/Symfony/Component/Console/Tests/Command/CommandTest.php b/src/Symfony/Component/Console/Tests/Command/CommandTest.php
@@ -457,6 +457,8 @@ public function testCommandAttribute()
         $this->assertSame('foo', $command->getName());
         $this->assertSame('desc', $command->getDescription());
         $this->assertSame('help', $command->getHelp());
+        $this->assertCount(2, $command->getUsages());
+        $this->assertStringContainsString('usage1', $command->getUsages()[0]);
         $this->assertTrue($command->isHidden());
         $this->assertSame(['f'], $command->getAliases());
     }
@@ -542,7 +544,7 @@ function createClosure()
     };
 }
 
-#[AsCommand(name: 'foo', description: 'desc', hidden: true, aliases: ['f'], help: 'help')]
+#[AsCommand(name: 'foo', description: 'desc', usages: ['usage1', 'usage2'], hidden: true, aliases: ['f'], help: 'help')]
 class Php8Command extends Command
 {
 }
diff --git a/src/Symfony/Component/Console/Tests/DependencyInjection/AddConsoleCommandPassTest.php b/src/Symfony/Component/Console/Tests/DependencyInjection/AddConsoleCommandPassTest.php
@@ -315,6 +315,7 @@ public function testProcessInvokableCommand()
         $definition->addTag('console.command', [
             'command' => 'invokable',
             'description' => 'The command description',
+            'usages' => ['usage1', 'usage2'],
             'help' => 'The %command.name% command help content.',
         ]);
         $container->setDefinition('invokable_command', $definition);
@@ -325,6 +326,8 @@ public function testProcessInvokableCommand()
         self::assertTrue($container->has('invokable_command.command'));
         self::assertSame('The command description', $command->getDescription());
         self::assertSame('The %command.name% command help content.', $command->getHelp());
+        self::assertCount(2, $command->getUsages());
+        $this->assertStringContainsString('usage1', $command->getUsages()[0]);
     }
 
     public function testProcessInvokableSignalableCommand()

Original file line number	Diff line number	Diff line change
`@@ -134,6 +134,10 @@ public function __construct(?string $name = null)`
`134`	`134`	`$this->setHelp($attribute?->help ?? '');`
`135`	`135`	`}`
`136`	`136`
	`137`	`+ foreach ($attribute?->usages ?? [] as $usage) {`
	`138`	`+ $this->addUsage($usage);`
	`139`	`+ }`
	`140`	`+`
`137`	`141`	`if (\is_callable($this) && (new \ReflectionMethod($this, 'execute'))->getDeclaringClass()->name === self::class) {`
`138`	`142`	`$this->code = new InvokableCommand($this, $this(...));`
`139`	`143`	`}`
Original file line number	Diff line number	Diff line change
`@@ -457,6 +457,8 @@ public function testCommandAttribute()`
`457`	`457`	`$this->assertSame('foo', $command->getName());`
`458`	`458`	`$this->assertSame('desc', $command->getDescription());`
`459`	`459`	`$this->assertSame('help', $command->getHelp());`
	`460`	`+ $this->assertCount(2, $command->getUsages());`
	`461`	`+ $this->assertStringContainsString('usage1', $command->getUsages()[0]);`
`460`	`462`	`$this->assertTrue($command->isHidden());`
`461`	`463`	`$this->assertSame(['f'], $command->getAliases());`
`462`	`464`	`}`
`@@ -542,7 +544,7 @@ function createClosure()`
`542`	`544`	`};`
`543`	`545`	`}`
`544`	`546`
`545`		`-#[AsCommand(name: 'foo', description: 'desc', hidden: true, aliases: ['f'], help: 'help')]`
	`547`	`+#[AsCommand(name: 'foo', description: 'desc', usages: ['usage1', 'usage2'], hidden: true, aliases: ['f'], help: 'help')]`
`546`	`548`	`class Php8Command extends Command`
`547`	`549`	`{`
`548`	`550`	`}`