diff --git a/src/Symfony/Component/Console/Application.php b/src/Symfony/Component/Console/Application.php index f77d57299f4fe..20fa7870af552 100644 --- 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 index 767d46ebb7ff1..02f1562012d7f 100644 --- a/src/Symfony/Component/Console/Attribute/AsCommand.php +++ b/src/Symfony/Component/Console/Attribute/AsCommand.php @@ -25,6 +25,7 @@ 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, @@ -32,6 +33,7 @@ public function __construct( 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 index f5e15ade7390d..1922e6562f130 100644 --- 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 index 23e3b662138c8..0ae82cf9ab57c 100644 --- 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 index 562627f4b6114..4a0ee42296032 100644 --- 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 index a3ecee43eea6c..44e8996293f8a 100644 --- 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 index 9ac660100ea0d..a11e6b5109acb 100644 --- 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()