Merge pull request #17955 from cakephp/feat/command-description

Add description for commands.

src/Command/CacheClearCommand.php

@@ -37,6 +37,14 @@ class CacheClearCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Clear all data in a single cache engine.';
+    }
+
+    /**
      * Hook method for defining this command's option parser.
      *
      * @see https://book.cakephp.org/5/en/console-commands/option-parsers.html
@@ -47,7 +55,7 @@ class CacheClearCommand extends Command
     {
         $parser = parent::buildOptionParser($parser);
         $parser
-            ->setDescription('Clear all data in a single cache engine')
+            ->setDescription(static::getDescription())
             ->addArgument('engine', [
                 'help' => 'The cache engine to clear.' .
                     'For example, `cake cache clear _cake_model_` will clear the model cache.' .

src/Command/CacheClearGroupCommand.php

@@ -38,6 +38,14 @@ class CacheClearGroupCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Clear all data in a single cache group.';
+    }
+
+    /**
      * Hook method for defining this command's option parser.
      *
      * @see https://book.cakephp.org/5/en/console-commands/option-parsers.html
@@ -47,7 +55,7 @@ class CacheClearGroupCommand extends Command
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
         $parser = parent::buildOptionParser($parser);
-        $parser->setDescription('Clear all data in a single cache group.');
+        $parser->setDescription(static::getDescription());
         $parser->addArgument('group', [
             'help' => 'The cache group to clear. For example, `cake cache clear_group mygroup` will clear ' .
                 'all cache items belonging to group "mygroup".',

src/Command/CacheClearallCommand.php

@@ -37,6 +37,14 @@ class CacheClearallCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Clear all data in all configured cache engines.';
+    }
+
+    /**
      * Hook method for defining this command's option parser.
      *
      * @see https://book.cakephp.org/5/en/console-commands/option-parsers.html
@@ -46,7 +54,7 @@ class CacheClearallCommand extends Command
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
         $parser = parent::buildOptionParser($parser);
-        $parser->setDescription('Clear all data in all configured cache engines.');
+        $parser->setDescription(static::getDescription());
 
         return $parser;
     }

src/Command/CacheListCommand.php

@@ -35,6 +35,14 @@ class CacheListCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Show a list of configured caches.';
+    }
+
+    /**
      * Hook method for defining this command's option parser.
      *
      * @see https://book.cakephp.org/5/en/console-commands/option-parsers.html
@@ -44,7 +52,7 @@ class CacheListCommand extends Command
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
         $parser = parent::buildOptionParser($parser);
-        $parser->setDescription('Show a list of configured caches.');
+        $parser->setDescription(static::getDescription());
 
         return $parser;
     }

src/Command/CompletionCommand.php

@@ -35,6 +35,14 @@ class CompletionCommand extends Command implements CommandCollectionAwareInterfa
     protected CommandCollection $commands;
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Used by shells like bash to autocomplete command name, options and arguments';
+    }
+
+    /**
      * Set the command collection used to get completion data on.
      *
      * @param \Cake\Console\CommandCollection $commands The command collection
@@ -64,7 +72,7 @@ class CompletionCommand extends Command implements CommandCollectionAwareInterfa
         }
 
         $parser->setDescription(
-            'Used by shells like bash to autocomplete command name, options and arguments'
+            static::getDescription()
         )->addArgument('mode', [
             'help' => 'The type of thing to get completion on.',
             'required' => true,

src/Command/I18nCommand.php

@@ -26,6 +26,14 @@ use Cake\Console\ConsoleOptionParser;
 class I18nCommand extends Command
 {
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'I18n commands let you generate .pot files to power translations in your application.';
+    }
+
+    /**
      * Execute interactive mode
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -79,9 +87,7 @@ class I18nCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'I18n commands let you generate .pot files to power translations in your application.'
-        );
+        $parser->setDescription(static::getDescription());
 
         return $parser;
     }

src/Command/I18nExtractCommand.php

@@ -33,14 +33,6 @@ use Cake\Utility\Inflector;
 class I18nExtractCommand extends Command
 {
     /**
-     * @inheritDoc
-     */
-    public static function defaultName(): string
-    {
-        return 'i18n extract';
-    }
-
-    /**
      * Paths to use when looking for strings
      *
      * @var list<string>
@@ -125,6 +117,22 @@ class I18nExtractCommand extends Command
     protected int $_countMarkerError = 0;
 
     /**
+     * @inheritDoc
+     */
+    public static function defaultName(): string
+    {
+        return 'i18n extract';
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Extract i18n POT files from application source files.';
+    }
+
+    /**
      * Method to interact with the user and get path selections.
      *
      * @param \Cake\Console\ConsoleIo $io The io instance.
@@ -354,11 +362,11 @@ class I18nExtractCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'Extract i18n POT files from application source files. ' .
+        $parser->setDescription([
+            static::getDescription(),
             'Source files are parsed and string literal format strings ' .
-            'provided to the <info>__</info> family of functions are extracted.'
-        )->addOption('app', [
+            'provided to the <info>__</info> family of functions are extracted.',
+        ])->addOption('app', [
             'help' => 'Directory where your application is located.',
         ])->addOption('paths', [
             'help' => 'Comma separated list of paths that are searched for source files.',

src/Command/I18nInitCommand.php

@@ -39,6 +39,14 @@ class I18nInitCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Initialize a language PO file from the POT file.';
+    }
+
+    /**
      * Execute the command
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -101,7 +109,7 @@ class I18nInitCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription('Initialize a language PO file from the POT file')
+        $parser->setDescription(static::getDescription())
            ->addOption('plugin', [
                'help' => 'The plugin to create a PO file in.',
                'short' => 'p',

src/Command/PluginAssetsCopyCommand.php

@@ -38,6 +38,14 @@ class PluginAssetsCopyCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return "Copy plugin assets to app's webroot.";
+    }
+
+    /**
      * Execute the command
      *
      * Copying plugin assets to app's webroot. For vendor namespaced plugin,
@@ -67,9 +75,9 @@ class PluginAssetsCopyCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription([
-            "Copy plugin assets to app's webroot.",
-        ])->addArgument('name', [
+        $parser->setDescription(
+            static::getDescription()
+        )->addArgument('name', [
             'help' => 'A specific plugin you want to copy assets for.',
             'required' => false,
         ])->addOption('overwrite', [

src/Command/PluginAssetsRemoveCommand.php

@@ -38,6 +38,14 @@ class PluginAssetsRemoveCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return "Remove plugin assets from app's webroot.";
+    }
+
+    /**
      * Execute the command
      *
      * Remove plugin assets from app's webroot.
@@ -76,9 +84,9 @@ class PluginAssetsRemoveCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription([
-            "Remove plugin assets from app's webroot.",
-        ])->addArgument('name', [
+        $parser->setDescription(
+            static::getDescription()
+        )->addArgument('name', [
             'help' => 'A specific plugin you want to remove.',
             'required' => false,
         ]);

src/Command/PluginAssetsSymlinkCommand.php

@@ -38,6 +38,14 @@ class PluginAssetsSymlinkCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return "Symlink (copy as fallback) plugin assets to app's webroot.";
+    }
+
+    /**
      * Execute the command
      *
      * Attempt to symlink plugin assets to app's webroot. If symlinking fails it
@@ -68,9 +76,9 @@ class PluginAssetsSymlinkCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription([
-            "Symlink (copy as fallback) plugin assets to app's webroot.",
-        ])->addArgument('name', [
+        $parser->setDescription(
+            static::getDescription()
+        )->addArgument('name', [
             'help' => 'A specific plugin you want to symlink assets for.',
             'required' => false,
         ])->addOption('overwrite', [

src/Command/PluginListCommand.php

@@ -37,6 +37,14 @@ class PluginListCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Displays all currently available plugins.';
+    }
+
+    /**
      * Displays all currently available plugins.
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -87,7 +95,7 @@ class PluginListCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription('Displays all currently available plugins.');
+        $parser->setDescription(static::getDescription());
         $parser->addOption('composer-path', [
             'help' => 'The absolute path to the composer.lock file to retrieve the versions from',
         ]);

src/Command/PluginLoadCommand.php

@@ -33,6 +33,13 @@ use Cake\Utility\Hash;
 class PluginLoadCommand extends Command
 {
     /**
+     * Config file
+     *
+     * @var string
+     */
+    protected string $configFile = CONFIG . 'plugins.php';
+
+    /**
      * @inheritDoc
      */
     public static function defaultName(): string
@@ -41,11 +48,12 @@ class PluginLoadCommand extends Command
     }
 
     /**
-     * Config file
-     *
-     * @var string
+     * @inheritDoc
      */
-    protected string $configFile = CONFIG . 'plugins.php';
+    public static function getDescription(): string
+    {
+        return 'Command for loading plugins.';
+    }
 
     /**
      * Execute the command
@@ -136,37 +144,43 @@ class PluginLoadCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription([
-                'Command for loading plugins.',
-            ])->addArgument('plugin', [
+        return $parser
+            ->setDescription(static::getDescription())
+            ->addArgument('plugin', [
                 'help' => 'Name of the plugin to load. Must be in CamelCase format. Example: cake plugin load Example',
                 'required' => true,
-            ])->addOption('only-debug', [
+            ])
+            ->addOption('only-debug', [
                 'boolean' => true,
                 'help' => 'Load the plugin only when `debug` is enabled.',
-            ])->addOption('only-cli', [
+            ])
+            ->addOption('only-cli', [
                 'boolean' => true,
                 'help' => 'Load the plugin only for CLI.',
-            ])->addOption('optional', [
+            ])
+            ->addOption('optional', [
                 'boolean' => true,
                 'help' => 'Do not throw an error if the plugin is not available.',
-            ])->addOption('no-bootstrap', [
+            ])
+            ->addOption('no-bootstrap', [
                 'boolean' => true,
                 'help' => 'Do not run the `bootstrap()` hook.',
-            ])->addOption('no-console', [
+            ])
+            ->addOption('no-console', [
                 'boolean' => true,
                 'help' => 'Do not run the `console()` hook.',
-            ])->addOption('no-middleware', [
+            ])
+            ->addOption('no-middleware', [
                 'boolean' => true,
                 'help' => 'Do not run the `middleware()` hook..',
-            ])->addOption('no-routes', [
+            ])
+            ->addOption('no-routes', [
                 'boolean' => true,
                 'help' => 'Do not run the `routes()` hook.',
-            ])->addOption('no-services', [
+            ])
+            ->addOption('no-services', [
                 'boolean' => true,
                 'help' => 'Do not run the `services()` hook.',
             ]);
-
-        return $parser;
     }
 }

src/Command/PluginLoadedCommand.php

@@ -35,6 +35,14 @@ class PluginLoadedCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Displays all currently loaded plugins.';
+    }
+
+    /**
      * Displays all currently loaded plugins.
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -57,7 +65,7 @@ class PluginLoadedCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription('Displays all currently loaded plugins.');
+        $parser->setDescription(static::getDescription());
 
         return $parser;
     }

src/Command/PluginUnloadCommand.php

@@ -43,6 +43,14 @@ class PluginUnloadCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Command for unloading plugins.';
+    }
+
+    /**
      * Execute the command
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -108,9 +116,9 @@ class PluginUnloadCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription([
-            'Command for unloading plugins.',
-        ])
+        $parser->setDescription(
+            static::getDescription()
+        )
         ->addArgument('plugin', [
             'help' => 'Name of the plugin to unload.',
             'required' => true,

src/Command/RoutesCheckCommand.php

@@ -38,6 +38,14 @@ class RoutesCheckCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Check a URL string against the routes.';
+    }
+
+    /**
      * Display all routes in an application
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -93,10 +101,10 @@ class RoutesCheckCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'Check a URL string against the routes. ' .
-            'Will output the routing parameters the route resolves to.'
-        )
+        $parser->setDescription([
+            static::getDescription(),
+            'Will output the routing parameters the route resolves to.',
+        ])
         ->addArgument('url', [
             'help' => 'The URL to check.',
             'required' => true,

src/Command/RoutesCommand.php

@@ -27,6 +27,14 @@ use Cake\Routing\Router;
 class RoutesCommand extends Command
 {
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Get the list of routes connected in this application.';
+    }
+
+    /**
      * Display all routes in an application
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -136,7 +144,7 @@ class RoutesCommand extends Command
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
         $parser
-            ->setDescription('Get the list of routes connected in this application.')
+            ->setDescription(static::getDescription())
             ->addOption('sort', [
                 'help' => 'Sorts alphabetically by route name A-Z',
                 'short' => 's',

src/Command/RoutesGenerateCommand.php

@@ -36,6 +36,14 @@ class RoutesGenerateCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Check a routing array against the routes.';
+    }
+
+    /**
      * Display all routes in an application
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -91,13 +99,13 @@ class RoutesGenerateCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'Check a routing array against the routes. ' .
+        $parser->setDescription([
+            static::getDescription(),
             'Will output the URL if there is a match.' .
             "\n\n" .
             'Routing parameters should be supplied in a key:value format. ' .
-            'For example `controller:Articles action:view 2`'
-        );
+            'For example `controller:Articles action:view 2`',
+        ]);
 
         return $parser;
     }

src/Command/SchemacacheBuildCommand.php

@@ -40,6 +40,14 @@ class SchemacacheBuildCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Build all metadata caches for the connection.';
+    }
+
+    /**
      * Display all routes in an application
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -77,10 +85,10 @@ class SchemacacheBuildCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'Build all metadata caches for the connection. If a ' .
-            'table name is provided, only that table will be cached.'
-        )->addOption('connection', [
+        $parser->setDescription([
+            static::getDescription(),
+            ' If a table name is provided, only that table will be cached.',
+        ])->addOption('connection', [
             'help' => 'The connection to build/clear metadata cache data for.',
             'short' => 'c',
             'default' => 'default',

src/Command/SchemacacheClearCommand.php

@@ -40,6 +40,14 @@ class SchemacacheClearCommand extends Command
     }
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Clear all metadata caches for the connection.';
+    }
+
+    /**
      * Display all routes in an application
      *
      * @param \Cake\Console\Arguments $args The command arguments.
@@ -77,10 +85,10 @@ class SchemacacheClearCommand extends Command
      */
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
-        $parser->setDescription(
-            'Clear all metadata caches for the connection. If a ' .
-            'table name is provided, only that table will be removed.'
-        )->addOption('connection', [
+        $parser->setDescription([
+            static::getDescription(),
+            'If a table name is provided, only that table will be removed.',
+        ])->addOption('connection', [
             'help' => 'The connection to build/clear metadata cache data for.',
             'short' => 'c',
             'default' => 'default',

src/Command/ServerCommand.php

@@ -71,6 +71,14 @@ class ServerCommand extends Command
     protected string $_iniPath = '';
 
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'PHP Built-in Server for CakePHP';
+    }
+
+    /**
      * Starts up the Command and displays the welcome message.
      * Allows for checking and configuring prior to command or main execution
      *
@@ -159,7 +167,7 @@ class ServerCommand extends Command
     public function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
     {
         $parser->setDescription([
-            'PHP Built-in Server for CakePHP',
+            static::getDescription(),
             "<warning>[WARN] Don't use this in a production environment</warning>",
         ])->addOption('host', [
             'short' => 'H',

src/Command/VersionCommand.php

@@ -26,6 +26,14 @@ use Cake\Core\Configure;
 class VersionCommand extends Command
 {
     /**
+     * @inheritDoc
+     */
+    public static function getDescription(): string
+    {
+        return 'Show the CakePHP version.';
+    }
+
+    /**
      * Print out the version of CakePHP in use.
      *
      * @param \Cake\Console\Arguments $args The command arguments.