Skip to content

Support alternative alias syntax for cross-platform compatibility#6155

Merged
swissspidy merged 34 commits intomainfrom
copilot/support-alias-syntax-cross-platform
Mar 12, 2026
Merged

Support alternative alias syntax for cross-platform compatibility#6155
swissspidy merged 34 commits intomainfrom
copilot/support-alias-syntax-cross-platform

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Nov 15, 2025

  • Configurator::add_alias() - handles both @foo: and aliases: { foo: } formats
  • Configurator::merge_yml() - processes aliases: key
  • Configurator::get_aliases() - normalizes runtime aliases (removes @ prefix)
  • CLI_Alias_Command::process_aliases() - writes aliases in aliases: format; whitelist of non-alias config keys is complete (all WP-CLI global params)
  • Added --alias=<name> to config-spec.php
  • Runner::init_config() - detects @foo before arg parsing; then checks --alias=foo
  • Runner::run_ssh_command() - condition now handles both @alias and --alias=foo when setting WP_CLI_RUNTIME_ALIAS
  • Runner::run_alias_group() - removed redundant duplicate logging/arg block; only correct @alias-prefixed log remains
  • Runner::run_ssh_command() filters --alias and @alias from forwarded args
  • Bash completions show @ prefix
  • Alias CRUD commands use find_alias_key() helper for both YAML formats
  • validate_alias_type() detects groups via numeric keys (not @ prefix)
  • build_aliases() preserves existing fields on update
  • New feature tests added
Original prompt

This section details on the original issue you should resolve

<issue_title>Support alternative alias syntax for better cross-platform compat</issue_title>
<issue_description>The wp-cli command configuration has some mismatches with Windows Powershell.

e.g. the ALIAS_REGEX constant used to configure remote instances because it uses the @ symbol as a prefix.
@ is used (like the $ character as a variable prefix) to expand the variable (converts a string variable in an array).

const ALIAS_REGEX = '^@[A-Za-z0-9-_\.\-]+$';

Would that be possible to allow overriding the constant with some filter?

Alternative question, why are we using @prod structure to define the aliases in the wp-cli.yml instead of an array of values like disabled_commands or require?</issue_description>

<agent_instructions>Add a new aliases configuration entry in the wp-cli.yml file
Allow to use --alias=foo instead of @foo to use an alias
Keep the classic arg notation working
Works properly with the local and global configs merged together even if both styles are used

Here's a previous attempt from a few years ago to give you some extra context:

diff --git a/php/WP_CLI/Configurator.php b/php/WP_CLI/Configurator.php
index 575aebee4..fc488902f 100644
--- a/php/WP_CLI/Configurator.php
+++ b/php/WP_CLI/Configurator.php
@@ -96,6 +96,49 @@ private function load_config_spec( $path ) {
 		$this->spec = $config_spec;
 	}
 
+	/**
+	 * Add the given alias to the global config
+	 *
+	 * @param $key
+	 * @param $value
+	 * @param $yml_file_dir
+	 *
+	 * @return void
+	 */
+	private function add_alias( $key, $value, $yml_file_dir ) {
+		if ( preg_match( '#' . self::ALIAS_REGEX . '#', $key ) ) {
+			// Remove the @ character from the alias name
+			$key = substr( $key, 1 );
+		}
+
+		$this->aliases[ $key ] = [];
+		$is_alias              = false;
+		foreach ( self::$alias_spec as $i ) {
+			if ( isset( $value[ $i ] ) ) {
+				if ( 'path' === $i && ! isset( $value['ssh'] ) ) {
+					self::absolutize( $value[ $i ], $yml_file_dir );
+				}
+				$this->aliases[ $key ][ $i ] = $value[ $i ];
+				$is_alias                    = true;
+			}
+		}
+
+		// If it's not an alias, it might be a group of aliases.
+		if ( ! $is_alias && is_array( $value ) ) {
+			$alias_group = [];
+			foreach ( $value as $k ) {
+				if ( preg_match( '#' . self::ALIAS_REGEX . '#', $k ) ) {
+					// Remove the @ character from the alias name
+					$alias_group[] = substr( $k, 1 );
+				} elseif ( array_key_exists( $k, $this->aliases ) ) {
+					// Check if the alias has been properly declared before adding it to the group
+					$alias_group[] = $k;
+				}
+			}
+			$this->aliases[ $key ] = $alias_group;
+		}
+	}
+
 	/**
 	 * Get declared configuration values as an array.
 	 *
@@ -257,26 +300,10 @@ public function merge_yml( $path, $current_alias = null ) {
 		$yml_file_dir = $path ? dirname( $path ) : false;
 		foreach ( $yaml as $key => $value ) {
 			if ( preg_match( '#' . self::ALIAS_REGEX . '#', $key ) ) {
-				$this->aliases[ $key ] = [];
-				$is_alias              = false;
-				foreach ( self::$alias_spec as $i ) {
-					if ( isset( $value[ $i ] ) ) {
-						if ( 'path' === $i && ! isset( $value['ssh'] ) ) {
-							self::absolutize( $value[ $i ], $yml_file_dir );
-						}
-						$this->aliases[ $key ][ $i ] = $value[ $i ];
-						$is_alias                    = true;
-					}
-				}
-				// If it's not an alias, it might be a group of aliases.
-				if ( ! $is_alias && is_array( $value ) ) {
-					$alias_group = [];
-					foreach ( $value as $k ) {
-						if ( preg_match( '#' . self::ALIAS_REGEX . '#', $k ) ) {
-							$alias_group[] = $k;
-						}
-					}
-					$this->aliases[ $key ] = $alias_group;
+				$this->add_alias( $key, $value, $yml_file_dir );
+			} elseif ( 'aliases' === $key ) {
+				foreach ( $value as $alias => $alias_config ) {
+					$this->add_alias( $alias, $alias_config, $yml_file_dir );
 				}
 			} elseif ( ! isset( $this->spec[ $key ] ) || false === $this->spec[ $key ]['file'] ) {
 				if ( isset( $this->extra_config[ $key ] )
diff --git a/php/WP_CLI/Runner.php b/php/WP_CLI/Runner.php
index 8dc80c80f..6b573bbb4 100644
--- a/php/WP_CLI/Runner.php
+++ b/php/WP_CLI/Runner.php
@@ -507,7 +507,9 @@ private function run_ssh_command( $connection_string ) {
 		}
 
 		foreach ( $wp_args as $k => $v ) {
-			if ( preg_match( '#--ssh=#', $v ) ) {
+			if ( preg_match( '#--ssh=|--alias=#', $v ) ) {
+				unset( $wp_args[ $k ] );
+			} elseif ( preg_match( '#' . Configurator::ALIAS_REGEX . '#', $v ) ) {
 				unset( $wp_args[ $k ] );
 			}
 		}
@@ -973,9 +975,19 @@ public function init_config() {
 
 		$argv = array_slice( $GLOBALS['argv'], 1 );
 
+		// Extract config from CLI args
+		list( $args, $assoc_args, $this->runtime_config ) = $configurator->parse_args( $argv );
+		list( $this->arguments, $this->assoc_args )       = self::back_compat_conversions(
+			$...

</details>

- Fixes wp-cli/wp-cli#5677

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/wp-cli/wp-cli/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 3 commits November 15, 2025 10:52
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
…s handling

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy swissspidy linked an issue Nov 15, 2025 that may be closed by this pull request
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Copilot AI changed the title [WIP] Add support for alternative alias syntax in wp-cli Support alternative alias syntax for cross-platform compatibility Nov 15, 2025
Copilot AI requested a review from swissspidy November 15, 2025 11:05
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@codecov
Copy link
Copy Markdown

codecov bot commented Nov 15, 2025

Codecov Report

❌ Patch coverage is 75.26316% with 47 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
php/WP_CLI/Configurator.php 0.00% 26 Missing ⚠️
php/commands/src/CLI_Alias_Command.php 86.23% 15 Missing ⚠️
php/WP_CLI/Runner.php 87.23% 6 Missing ⚠️

📢 Thoughts on this report? Let us know!

This comment was marked as resolved.

swissspidy and others added 2 commits November 15, 2025 17:26
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@swissspidy

This comment was marked as resolved.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

This comment was marked as resolved.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Copilot AI and others added 2 commits December 14, 2025 21:28
Three improvements based on code review:
1. Fixed validate_alias_type to properly detect group aliases - checks for numeric keys instead of @-prefixed values since groups are now stored as ['foo', 'bar'] without @ prefix
2. Fixed indentation inconsistency in build_aliases elseif block
3. Changed process_aliases to write aliases using the new 'aliases:' format instead of @foo: format for better cross-platform compatibility and consistency

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy swissspidy marked this pull request as ready for review December 14, 2025 21:42
@swissspidy swissspidy requested a review from a team as a code owner December 14, 2025 21:42
@swissspidy

This comment was marked as resolved.

gemini-code-assist[bot]

This comment was marked as resolved.

- Runner.php: Extend SSH command runtime alias condition to also match --alias=foo syntax (parity with @foo)
- CLI_Alias_Command.php: Expand the non-alias config key whitelist to include all standard WP-CLI global parameters (exec, disabled_commands, apache_modules, color, debug, prompt, quiet, allow-root, skip-plugins, skip-themes, skip-packages, context, alias) to prevent config arrays from being incorrectly moved to the aliases: section
- Runner.php: Remove redundant duplicate block in run_alias_group that was logging without @ prefix and using verbose array_map before the correct block

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy swissspidy added this to the 3.0.0 milestone Mar 12, 2026
@swissspidy swissspidy merged commit 7ed1ad1 into main Mar 12, 2026
69 checks passed
@swissspidy swissspidy deleted the copilot/support-alias-syntax-cross-platform branch March 12, 2026 15:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support alternative alias syntax for better cross-platform compat

3 participants