feature #39851 [Console] enable describing commands in ways that make the list command lazy (nicolas-grekas)

nicolas-grekas · nicolas-grekas · commit 08f41af6b3a9 · 2021-01-20T13:56:01.000+01:00
This PR was merged into the 5.3-dev branch.

Discussion
----------

[Console] enable describing commands in ways that make the `list` command lazy

| Q             | A
| ------------- | ---
| Branch?       | 5.x
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Fix #33804
| License       | MIT
| Doc PR        | -

This PR improves the way one can describe a command so that the `list` command can be made lazy:
- when provided using the `$defaultName` property or the `console.command` tag, the name of a command is now exploded using the `|` character. The first name in the list defines the name of the command, the other ones its aliases. When the first name is the empty string, the second name is used instead, and the command is declared as hidden.
- a new `$defaultDescription` static property and a new `description` tag attribute allow for defining the commands' description while registering them.

Together, this is enough to make the `list` command lazy, because this command only accesses each command's name, aliases, hidden-status, and description.

On the implementation side, this PR adds a `LazyCommand` class that proxies regular commands to make them lazy for the target purpose.

This PR will enable support for attributes for configuring a command name+description+etc.
e.g. using the concepts in #39804:
`#[CommandAutoTag(name: 'foo:bar', desc: 'boo', hidden: true)]#`

The attribute could very well split the `hidden` and `aliases` settings apart - while the underlying code and pre-PHP8 apps would use the compact form, because dealing with many static properties + methods would be a maintenance pain imho.

Commits
-------

8a1a1b8171 [Console] enable describing commands in ways that make the `list` command lazy
diff --git a/Command/AboutCommand.php b/Command/AboutCommand.php
@@ -30,14 +30,15 @@
 class AboutCommand extends Command
 {
     protected static $defaultName = 'about';
+    protected static $defaultDescription = 'Displays information about the current project';
 
     /**
      * {@inheritdoc}
      */
     protected function configure()
     {
         $this
-            ->setDescription('Displays information about the current project')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOT'
 The <info>%command.name%</info> command displays information about the current Symfony project.
 
diff --git a/Command/AssetsInstallCommand.php b/Command/AssetsInstallCommand.php
@@ -40,6 +40,7 @@ class AssetsInstallCommand extends Command
     public const METHOD_RELATIVE_SYMLINK = 'relative symlink';
 
     protected static $defaultName = 'assets:install';
+    protected static $defaultDescription = 'Installs bundles web assets under a public directory';
 
     private $filesystem;
     private $projectDir;
@@ -64,7 +65,7 @@ protected function configure()
             ->addOption('symlink', null, InputOption::VALUE_NONE, 'Symlinks the assets instead of copying it')
             ->addOption('relative', null, InputOption::VALUE_NONE, 'Make relative symlinks')
             ->addOption('no-cleanup', null, InputOption::VALUE_NONE, 'Do not remove the assets of the bundles that no longer exist')
-            ->setDescription('Installs bundles web assets under a public directory')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOT'
 The <info>%command.name%</info> command installs bundle assets into a given
 directory (e.g. the <comment>public</comment> directory).
diff --git a/Command/CacheClearCommand.php b/Command/CacheClearCommand.php
@@ -36,6 +36,7 @@
 class CacheClearCommand extends Command
 {
     protected static $defaultName = 'cache:clear';
+    protected static $defaultDescription = 'Clears the cache';
 
     private $cacheClearer;
     private $filesystem;
@@ -58,7 +59,7 @@ protected function configure()
                 new InputOption('no-warmup', '', InputOption::VALUE_NONE, 'Do not warm up the cache'),
                 new InputOption('no-optional-warmers', '', InputOption::VALUE_NONE, 'Skip optional cache warmers (faster)'),
             ])
-            ->setDescription('Clears the cache')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command clears the application cache for a given environment
 and debug mode:
diff --git a/Command/CachePoolClearCommand.php b/Command/CachePoolClearCommand.php
@@ -28,6 +28,7 @@
 final class CachePoolClearCommand extends Command
 {
     protected static $defaultName = 'cache:pool:clear';
+    protected static $defaultDescription = 'Clears cache pools';
 
     private $poolClearer;
 
@@ -47,7 +48,7 @@ protected function configure()
             ->setDefinition([
                 new InputArgument('pools', InputArgument::IS_ARRAY | InputArgument::REQUIRED, 'A list of cache pools or cache pool clearers'),
             ])
-            ->setDescription('Clears cache pools')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command clears the given cache pools or cache pool clearers.
 
diff --git a/Command/CachePoolDeleteCommand.php b/Command/CachePoolDeleteCommand.php
@@ -26,6 +26,7 @@
 final class CachePoolDeleteCommand extends Command
 {
     protected static $defaultName = 'cache:pool:delete';
+    protected static $defaultDescription = 'Deletes an item from a cache pool';
 
     private $poolClearer;
 
@@ -46,7 +47,7 @@ protected function configure()
                 new InputArgument('pool', InputArgument::REQUIRED, 'The cache pool from which to delete an item'),
                 new InputArgument('key', InputArgument::REQUIRED, 'The cache key to delete from the pool'),
             ])
-            ->setDescription('Deletes an item from a cache pool')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> deletes an item from a given cache pool.
 
diff --git a/Command/CachePoolListCommand.php b/Command/CachePoolListCommand.php
@@ -24,6 +24,7 @@
 final class CachePoolListCommand extends Command
 {
     protected static $defaultName = 'cache:pool:list';
+    protected static $defaultDescription = 'List available cache pools';
 
     private $poolNames;
 
@@ -40,7 +41,7 @@ public function __construct(array $poolNames)
     protected function configure()
     {
         $this
-            ->setDescription('List available cache pools')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command lists all available cache pools.
 EOF
diff --git a/Command/CachePoolPruneCommand.php b/Command/CachePoolPruneCommand.php
@@ -25,6 +25,7 @@
 final class CachePoolPruneCommand extends Command
 {
     protected static $defaultName = 'cache:pool:prune';
+    protected static $defaultDescription = 'Prunes cache pools';
 
     private $pools;
 
@@ -44,7 +45,7 @@ public function __construct(iterable $pools)
     protected function configure()
     {
         $this
-            ->setDescription('Prunes cache pools')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command deletes all expired items from all pruneable pools.
 
diff --git a/Command/CacheWarmupCommand.php b/Command/CacheWarmupCommand.php
@@ -29,6 +29,7 @@
 class CacheWarmupCommand extends Command
 {
     protected static $defaultName = 'cache:warmup';
+    protected static $defaultDescription = 'Warms up an empty cache';
 
     private $cacheWarmer;
 
@@ -48,7 +49,7 @@ protected function configure()
             ->setDefinition([
                 new InputOption('no-optional-warmers', '', InputOption::VALUE_NONE, 'Skip optional cache warmers (faster)'),
             ])
-            ->setDescription('Warms up an empty cache')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command warms up the cache.
 
diff --git a/Command/ConfigDebugCommand.php b/Command/ConfigDebugCommand.php
@@ -33,6 +33,7 @@
 class ConfigDebugCommand extends AbstractConfigCommand
 {
     protected static $defaultName = 'debug:config';
+    protected static $defaultDescription = 'Dumps the current configuration for an extension';
 
     /**
      * {@inheritdoc}
@@ -44,7 +45,7 @@ protected function configure()
                 new InputArgument('name', InputArgument::OPTIONAL, 'The bundle name or the extension alias'),
                 new InputArgument('path', InputArgument::OPTIONAL, 'The configuration option path'),
             ])
-            ->setDescription('Dumps the current configuration for an extension')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command dumps the current configuration for an
 extension/bundle.
diff --git a/Command/ConfigDumpReferenceCommand.php b/Command/ConfigDumpReferenceCommand.php
@@ -36,6 +36,7 @@
 class ConfigDumpReferenceCommand extends AbstractConfigCommand
 {
     protected static $defaultName = 'config:dump-reference';
+    protected static $defaultDescription = 'Dumps the default configuration for an extension';
 
     /**
      * {@inheritdoc}
@@ -48,7 +49,7 @@ protected function configure()
                 new InputArgument('path', InputArgument::OPTIONAL, 'The configuration option path'),
                 new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (yaml or xml)', 'yaml'),
             ])
-            ->setDescription('Dumps the default configuration for an extension')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command dumps the default configuration for an
 extension/bundle.
diff --git a/Command/ContainerDebugCommand.php b/Command/ContainerDebugCommand.php
@@ -35,6 +35,7 @@ class ContainerDebugCommand extends Command
     use BuildDebugContainerTrait;
 
     protected static $defaultName = 'debug:container';
+    protected static $defaultDescription = 'Displays current services for an application';
 
     /**
      * {@inheritdoc}
@@ -57,7 +58,7 @@ protected function configure()
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw description'),
                 new InputOption('deprecations', null, InputOption::VALUE_NONE, 'Displays deprecations generated when compiling and warming up the container'),
             ])
-            ->setDescription('Displays current services for an application')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command displays all configured <comment>public</comment> services:
 
diff --git a/Command/ContainerLintCommand.php b/Command/ContainerLintCommand.php
@@ -30,6 +30,7 @@
 final class ContainerLintCommand extends Command
 {
     protected static $defaultName = 'lint:container';
+    protected static $defaultDescription = 'Ensures that arguments injected into services match type declarations';
 
     /**
      * @var ContainerBuilder
@@ -42,7 +43,7 @@ final class ContainerLintCommand extends Command
     protected function configure()
     {
         $this
-            ->setDescription('Ensures that arguments injected into services match type declarations')
+            ->setDescription(self::$defaultDescription)
             ->setHelp('This command parses service definitions and ensures that injected values match the type declarations of each services\' class.')
         ;
     }
diff --git a/Command/DebugAutowiringCommand.php b/Command/DebugAutowiringCommand.php
@@ -30,6 +30,7 @@
 class DebugAutowiringCommand extends ContainerDebugCommand
 {
     protected static $defaultName = 'debug:autowiring';
+    protected static $defaultDescription = 'Lists classes/interfaces you can use for autowiring';
     private $supportsHref;
     private $fileLinkFormatter;
 
@@ -50,7 +51,7 @@ protected function configure()
                 new InputArgument('search', InputArgument::OPTIONAL, 'A search filter'),
                 new InputOption('all', null, InputOption::VALUE_NONE, 'Show also services that are not aliased'),
             ])
-            ->setDescription('Lists classes/interfaces you can use for autowiring')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command displays the classes and interfaces that
 you can use as type-hints for autowiring:
diff --git a/Command/EventDispatcherDebugCommand.php b/Command/EventDispatcherDebugCommand.php
@@ -33,6 +33,7 @@ class EventDispatcherDebugCommand extends Command
     private const DEFAULT_DISPATCHER = 'event_dispatcher';
 
     protected static $defaultName = 'debug:event-dispatcher';
+    protected static $defaultDescription = 'Displays configured listeners for an application';
     private $dispatchers;
 
     public function __construct(ContainerInterface $dispatchers)
@@ -54,7 +55,7 @@ protected function configure()
                 new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format  (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw description'),
             ])
-            ->setDescription('Displays configured listeners for an application')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command displays all configured listeners:
 
diff --git a/Command/RouterDebugCommand.php b/Command/RouterDebugCommand.php
@@ -36,6 +36,7 @@ class RouterDebugCommand extends Command
     use BuildDebugContainerTrait;
 
     protected static $defaultName = 'debug:router';
+    protected static $defaultDescription = 'Displays current routes for an application';
     private $router;
     private $fileLinkFormatter;
 
@@ -59,7 +60,7 @@ protected function configure()
                 new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt'),
                 new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw route(s)'),
             ])
-            ->setDescription('Displays current routes for an application')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> displays the configured routes:
 
diff --git a/Command/RouterMatchCommand.php b/Command/RouterMatchCommand.php
@@ -31,6 +31,7 @@
 class RouterMatchCommand extends Command
 {
     protected static $defaultName = 'router:match';
+    protected static $defaultDescription = 'Helps debug routes by simulating a path info match';
 
     private $router;
     private $expressionLanguageProviders;
@@ -55,7 +56,7 @@ protected function configure()
                 new InputOption('scheme', null, InputOption::VALUE_REQUIRED, 'Sets the URI scheme (usually http or https)'),
                 new InputOption('host', null, InputOption::VALUE_REQUIRED, 'Sets the URI host'),
             ])
-            ->setDescription('Helps debug routes by simulating a path info match')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> shows which routes match a given request and which don't and for what reason:
 
diff --git a/Command/SecretsDecryptToLocalCommand.php b/Command/SecretsDecryptToLocalCommand.php
@@ -27,6 +27,7 @@
 final class SecretsDecryptToLocalCommand extends Command
 {
     protected static $defaultName = 'secrets:decrypt-to-local';
+    protected static $defaultDescription = 'Decrypts all secrets and stores them in the local vault';
 
     private $vault;
     private $localVault;
@@ -42,7 +43,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Decrypts all secrets and stores them in the local vault')
+            ->setDescription(self::$defaultDescription)
             ->addOption('force', 'f', InputOption::VALUE_NONE, 'Forces overriding of secrets that already exist in the local vault')
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command decrypts all secrets and copies them in the local vault.
diff --git a/Command/SecretsEncryptFromLocalCommand.php b/Command/SecretsEncryptFromLocalCommand.php
@@ -26,6 +26,7 @@
 final class SecretsEncryptFromLocalCommand extends Command
 {
     protected static $defaultName = 'secrets:encrypt-from-local';
+    protected static $defaultDescription = 'Encrypts all local secrets to the vault';
 
     private $vault;
     private $localVault;
@@ -41,7 +42,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Encrypts all local secrets to the vault')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command encrypts all locally overridden secrets to the vault.
 
diff --git a/Command/SecretsGenerateKeysCommand.php b/Command/SecretsGenerateKeysCommand.php
@@ -29,6 +29,7 @@
 final class SecretsGenerateKeysCommand extends Command
 {
     protected static $defaultName = 'secrets:generate-keys';
+    protected static $defaultDescription = 'Generates new encryption keys';
 
     private $vault;
     private $localVault;
@@ -44,7 +45,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Generates new encryption keys')
+            ->setDescription(self::$defaultDescription)
             ->addOption('local', 'l', InputOption::VALUE_NONE, 'Updates the local vault.')
             ->addOption('rotate', 'r', InputOption::VALUE_NONE, 'Re-encrypts existing secrets with the newly generated keys.')
             ->setHelp(<<<'EOF'
diff --git a/Command/SecretsListCommand.php b/Command/SecretsListCommand.php
@@ -30,6 +30,7 @@
 final class SecretsListCommand extends Command
 {
     protected static $defaultName = 'secrets:list';
+    protected static $defaultDescription = 'Lists all secrets';
 
     private $vault;
     private $localVault;
@@ -45,7 +46,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Lists all secrets')
+            ->setDescription(self::$defaultDescription)
             ->addOption('reveal', 'r', InputOption::VALUE_NONE, 'Display decrypted values alongside names')
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command list all stored secrets.
diff --git a/Command/SecretsRemoveCommand.php b/Command/SecretsRemoveCommand.php
@@ -29,6 +29,7 @@
 final class SecretsRemoveCommand extends Command
 {
     protected static $defaultName = 'secrets:remove';
+    protected static $defaultDescription = 'Removes a secret from the vault';
 
     private $vault;
     private $localVault;
@@ -44,7 +45,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Removes a secret from the vault')
+            ->setDescription(self::$defaultDescription)
             ->addArgument('name', InputArgument::REQUIRED, 'The name of the secret')
             ->addOption('local', 'l', InputOption::VALUE_NONE, 'Updates the local vault.')
             ->setHelp(<<<'EOF'
diff --git a/Command/SecretsSetCommand.php b/Command/SecretsSetCommand.php
@@ -30,6 +30,7 @@
 final class SecretsSetCommand extends Command
 {
     protected static $defaultName = 'secrets:set';
+    protected static $defaultDescription = 'Sets a secret in the vault';
 
     private $vault;
     private $localVault;
@@ -45,7 +46,7 @@ public function __construct(AbstractVault $vault, AbstractVault $localVault = nu
     protected function configure()
     {
         $this
-            ->setDescription('Sets a secret in the vault')
+            ->setDescription(self::$defaultDescription)
             ->addArgument('name', InputArgument::REQUIRED, 'The name of the secret')
             ->addArgument('file', InputArgument::OPTIONAL, 'A file where to read the secret from or "-" for reading from STDIN')
             ->addOption('local', 'l', InputOption::VALUE_NONE, 'Updates the local vault.')
diff --git a/Command/TranslationDebugCommand.php b/Command/TranslationDebugCommand.php
@@ -47,6 +47,7 @@ class TranslationDebugCommand extends Command
     public const MESSAGE_EQUALS_FALLBACK = 2;
 
     protected static $defaultName = 'debug:translation';
+    protected static $defaultDescription = 'Displays translation messages information';
 
     private $translator;
     private $reader;
@@ -83,7 +84,7 @@ protected function configure()
                 new InputOption('only-unused', null, InputOption::VALUE_NONE, 'Displays only unused messages'),
                 new InputOption('all', null, InputOption::VALUE_NONE, 'Load messages from all registered bundles'),
             ])
-            ->setDescription('Displays translation messages information')
+            ->setDescription(self::$defaultDescription)
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command helps finding unused or missing translation
 messages and comparing them with the fallback ones by inspecting the
diff --git a/Command/TranslationUpdateCommand.php b/Command/TranslationUpdateCommand.php
diff --git a/Command/WorkflowDumpCommand.php b/Command/WorkflowDumpCommand.php
diff --git a/Resources/config/console.php b/Resources/config/console.php

Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@`
`24`	`24`	`final class CachePoolListCommand extends Command`
`25`	`25`	`{`
`26`	`26`	`protected static $defaultName = 'cache:pool:list';`
	`27`	`+ protected static $defaultDescription = 'List available cache pools';`
`27`	`28`
`28`	`29`	`private $poolNames;`
`29`	`30`
`@@ -40,7 +41,7 @@ public function __construct(array $poolNames)`
`40`	`41`	`protected function configure()`
`41`	`42`	`{`
`42`	`43`	`$this`
`43`		`- ->setDescription('List available cache pools')`
	`44`	`+ ->setDescription(self::$defaultDescription)`
`44`	`45`	`->setHelp(<<<'EOF'`
`45`	`46`	`The <info>%command.name%</info> command lists all available cache pools.`
`46`	`47`	`EOF`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,7 @@`
`25`	`25`	`final class CachePoolPruneCommand extends Command`
`26`	`26`	`{`
`27`	`27`	`protected static $defaultName = 'cache:pool:prune';`
	`28`	`+ protected static $defaultDescription = 'Prunes cache pools';`
`28`	`29`
`29`	`30`	`private $pools;`
`30`	`31`
`@@ -44,7 +45,7 @@ public function __construct(iterable $pools)`
`44`	`45`	`protected function configure()`
`45`	`46`	`{`
`46`	`47`	`$this`
`47`		`- ->setDescription('Prunes cache pools')`
	`48`	`+ ->setDescription(self::$defaultDescription)`
`48`	`49`	`->setHelp(<<<'EOF'`
`49`	`50`	`The <info>%command.name%</info> command deletes all expired items from all pruneable pools.`
`50`	`51`