Merge pull request #8256 from cakephp/5.next-console-ux

Document console UX improvements (cakephp/cakephp#19303)

Author: markstory

docs/en/appendices/5-4-migration-guide.md

@@ -20,6 +20,20 @@ bin/cake upgrade rector --rules cakephp54 <path/to/app/src>
 
 - `BaseCommand::initialize()` is now being triggered **AFTER** arguments and options have been parsed.
 
+### Console
+
+Running `bin/cake` without providing a command name no longer displays the
+"No command provided" error message. Instead, the `help` command is shown
+directly.
+
+The `help` command is now hidden from command listings (via
+`CommandHiddenInterface`). It remains accessible by running `bin/cake help` or
+`bin/cake help <command>`.
+
+The CakePHP version header in help output is now only shown when the CakePHP
+version can be determined. When used outside a CakePHP application (where the
+version is reported as `unknown`), the header is omitted.
+
 ### I18n
 
 - `Number::parseFloat()` now returns `null` instead of `0.0` when parsing
@@ -63,6 +77,12 @@ bin/cake upgrade rector --rules cakephp54 <path/to/app/src>
   without needing to pass them down from the `execute()` method. **This will be the default in CakePHP 6.0**
   as those arguments will be removed from the `execute()` method signature.
 
+### Console
+
+- Added `ConsoleHelpHeaderProviderInterface` to allow host applications to
+  provide a custom header in console help output.
+  See [Customizing the Help Header](../console-commands/commands#customizing-the-help-header).
+
 ### Controller
 
 - Added `#[RequestToDto]` attribute for automatic mapping of request data to

docs/en/console-commands/commands.md

@@ -360,6 +360,44 @@ public function console(CommandCollection $commands): CommandCollection
 `CommandCollection::replace()` was added.
 :::
 
+## Customizing the Help Header
+
+By default, `bin/cake help` displays a CakePHP version header at the top of
+command listings. When the CakePHP version cannot be determined (e.g. when the
+console package is used outside a CakePHP application), the header is omitted
+automatically.
+
+You can replace the default header with your own by implementing
+`Cake\Core\ConsoleHelpHeaderProviderInterface` on the application class passed
+to `CommandRunner`:
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace App;
+
+use Cake\Core\ConsoleHelpHeaderProviderInterface;
+use Cake\Http\BaseApplication;
+
+class Application extends BaseApplication implements ConsoleHelpHeaderProviderInterface
+{
+    public function getConsoleHelpHeader(): string
+    {
+        return '<info>MyApp:</info> 1.4.0 (env: prod)';
+    }
+}
+```
+
+When this interface is implemented, `CommandRunner` passes the return value of
+`getConsoleHelpHeader()` to `HelpCommand`, replacing the default CakePHP header.
+Console markup tags such as `<info>` and `<comment>` are supported in the
+returned string.
+
+::: info Added in version 5.4.0
+`ConsoleHelpHeaderProviderInterface` was added.
+:::
+
 ## Tree Output Helper
 
 The `TreeHelper` outputs an array as a tree structure. This is useful for