Skip to content

feat: add support for command name aliases#10289

Open
paulbalandan wants to merge 1 commit into
codeigniter4:4.8from
paulbalandan:command-name-aliases
Open

feat: add support for command name aliases#10289
paulbalandan wants to merge 1 commit into
codeigniter4:4.8from
paulbalandan:command-name-aliases

Conversation

@paulbalandan
Copy link
Copy Markdown
Member

Description

Modern commands (AbstractCommand + #[Command]) can now declare one or more aliases through a new aliases list on the #[Command] attribute. An alias is an alternative name the same command can be invoked by, useful for short forms or for renames that keep the old name working.

#[Command(
    name: 'app:deploy',
    description: 'Deploys the application.',
    group: 'App',
    aliases: ['app:ship', 'deploy'],
)]
class AppDeploy extends AbstractCommand { /* ... */ }

All of these then reach the same command:

php spark app:deploy
php spark app:ship
php spark deploy

What changed

  • Declaration & validation (#[Command]): the aliases parameter takes a list of strings. Each alias is validated with the same rules as name (non-empty, no whitespace, optionally colon-namespaced, no leading/trailing/consecutive colons), must differ from the command name, and must be unique within the command. Invalid aliases are reported at discovery, the same way an invalid name already is.
  • Resolution (Commands): aliases are kept in an alias => canonical name map and resolved at lookup. The real command name is always checked first, so an alias can never shadow a command. getCommand(), verifyCommand(), and hasModernCommand() all resolve aliases, so php spark <alias>, command('<alias>'), and service('commands')->runCommand('<alias>', ...) all work.
  • Collisions fail hard: if an alias collides with an existing command name or with another command's alias, discovery throws. The runner cannot guess which command was meant, so the problem is surfaced immediately. This is stricter than the existing legacy/modern duplicate-name case, which only warns. A colliding alias is always a configuration mistake.
  • help <command> gains an Aliases: section, and help <alias> resolves to the canonical command (its usage line still shows the canonical name).
  • spark list renders each alias as its own row marked [alias of <command>], sorted within the command's group. list --simple includes alias names too, since they are invokable.
  • New accessors: AbstractCommand::getAliases() and Commands::getCommandAliases().

Sample list output:

Cache
  cache:clear       Clears the current system caches.
  cache:flush       [alias of cache:clear]
  cache:info        Shows file cache information in the current system.
  cc                [alias of cache:clear]

Notes

  • Modern commands only. Legacy BaseCommand commands are unchanged.
  • This adds the mechanism only. No built-in command declares an alias yet; assigning aliases to specific built-ins can follow in a separate PR.
  • Console::getCommand() still returns the raw token the user typed (the alias), which is what logging and inspection want.
  • New language keys: Commands.invalidCommandAlias, Commands.commandAliasSameAsName, Commands.duplicateCommandAlias, Commands.aliasClashesWithCommandName, Commands.aliasClashesWithAlias, CLI.commandAlias, and CLI.helpAliases.

Checklist:

  • Securely signed commits
  • Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
  • Unit testing, with >80% coverage
  • User guide updated
  • Conforms to style guide

@github-actions github-actions Bot added the 4.8 PRs that target the `4.8` branch. label Jun 8, 2026
@paulbalandan paulbalandan added enhancement PRs that improve existing functionalities 4.8 PRs that target the `4.8` branch. and removed 4.8 PRs that target the `4.8` branch. labels Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.8 PRs that target the `4.8` branch. enhancement PRs that improve existing functionalities

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant