PHANTOM
🇮🇳 IN
Skip to content

Console UX improvements for help output and third-party integration#19303

Open
josbeir wants to merge 2 commits into5.nextfrom
5.next-command-cleanup
Open

Console UX improvements for help output and third-party integration#19303
josbeir wants to merge 2 commits into5.nextfrom
5.next-command-cleanup

Conversation

@josbeir
Copy link
Contributor

@josbeir josbeir commented Feb 25, 2026

This PR improves Console help UX and makes behavior more suitable when the package is embedded in non-CakePHP applications.

Why this matters for third-party usage

These changes are particularly useful for third-party implementations because help output should reflect the host app, not assume CakePHP context. Without this, users can see misleading framework/version branding and noisier command discovery flow.

What changed

  • Running with no command now doesn't show the “no command provided” error line. (this was really BAD UX in my book)
  • help is now hidden from command listings via CommandHiddenInterface.
    • Reason: when users are already in help output, listing help adds noise and little value; help remains available via the help command.
  • Added a pluggable header extension point so host apps can provide their own help header:
    • ConsoleHelpHeaderProviderInterface.php
    • wired through CommandRunner.php
  • Default CakePHP header in HelpCommand.php now appears only in CakePHP context (known Cake version) and is shown in non verbose mode too. (good UX)
  • Improved readability of compact command output in HelpCommand.php:
    • tuned spacing between command and description
    • visual distinction between group headers and command names

Example: custom Console help header

Implement ConsoleHelpHeaderProviderInterface on the application class used by CommandRunner:

<?php
declare(strict_types=1);

namespace App;

use Cake\Console\CommandCollection;
use Cake\Core\ConsoleApplicationInterface;
use Cake\Core\ConsoleHelpHeaderProviderInterface;

final class Application implements ConsoleApplicationInterface, ConsoleHelpHeaderProviderInterface
{
    public function bootstrap(): void
    {
        // bootstrap logic
    }

    public function console(CommandCollection $commands): CommandCollection
    {
        return $commands;
    }

    public function getConsoleHelpHeader(): string
    {
        return '<info>Foo Commander:</info> 1.4.0 (env: prod)';
    }
}

When this interface is implemented, the custom header is shown in help output instead of the default CakePHP header.

Examples in a Cake context

image image

Examples in a Custom app context

BEFORE:

image

AFTER:

image

Copilot AI review requested due to automatic review settings February 25, 2026 08:43
@josbeir josbeir changed the base branch from 5.x to 5.next February 25, 2026 08:43

This comment was marked as outdated.

@markstory markstory added this to the 5.4.0 milestone Feb 25, 2026
'unique',
'welcome',
'cache',
'help',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't help still be a command?

Copy link
Contributor Author

@josbeir josbeir Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is but adding CommandHiddenInterface effecitvly hides this command from execution output, as this is an integration test it will not be in the output here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants