This PR adds support for loading system-wide configuration files with cross-platform support, enabling system administrators to provide shared WP-CLI configurations for all users on Linux, macOS, and Windows.

Configuration Loading Order

The implementation establishes the following configuration priority hierarchy:

1. System config: Platform-specific system-wide location (lowest priority)
2. Global config: ~/.wp-cli/config.yml or WP_CLI_CONFIG_PATH (medium priority)
3. Project config: wp-cli.yml or wp-cli.local.yml (highest priority)

Each subsequent config file can override settings from the previous ones, allowing system-wide defaults to be overridden by user-specific settings, which can be further overridden by project-specific settings.

System Config Locations

The system-wide configuration file is loaded from different locations depending on the operating system:

• Linux: /etc/wp-cli/config.yml
• macOS: /Library/Application Support/WP-CLI/config.yml
• Windows: C:\ProgramData\wp-cli\config.yml (uses ProgramData environment variable if available, falls back to hardcoded path)

The path can be overridden using the WP_CLI_SYSTEM_SETTINGS_PATH environment variable.

Changes Made

Core Implementation

Runner.php:

• Added $system_config_path and $system_config_path_debug properties
• Added get_system_config_path() method with cross-platform OS detection
• Support for Linux (/etc/wp-cli/config.yml), macOS (/Library/Application Support/WP-CLI/config.yml), and Windows (C:\ProgramData\wp-cli\config.yml)
• Modified init_config() to load system config first before global and project configs
• Added debug message output for system config status
• Support for WP_CLI_SYSTEM_SETTINGS_PATH environment variable to override the default path

LoadRequiredCommand.php:

• Added 'system' scope to error messages for missing required files
• Added defensive isset() check to prevent undefined array key warnings

Testing

config.feature:

• Added Behat test scenarios for WP_CLI_SYSTEM_SETTINGS_PATH environment variable
• Test custom system config path and debug output verification
• Test system config with aliases
• Test that user config properly overrides system config settings (demonstrating priority hierarchy)

Features Enabled

This implementation enables system administrators to:

• Provide default WP-CLI configurations for all users on Linux, macOS, and Windows
• Define shared alias definitions across multiple user accounts
• Set organization-wide command defaults and disabled commands
• Centralize required file loading for custom commands
• Override the default system config path via environment variable for flexibility

Testing Notes

The implementation gracefully handles the absence of system config files:

• Returns false from get_system_config_path() when file doesn't exist
• Configurator::merge_yml() safely handles false by returning empty array
• Debug message indicates "No readable system config found"

Behat tests validate the custom WP_CLI_SYSTEM_SETTINGS_PATH functionality, including proper config loading, alias support, and config priority hierarchy.

Backwards Compatibility

This feature is fully backwards compatible with existing WP-CLI installations. When the system config file doesn't exist, WP-CLI behaves exactly as before with no performance impact or breaking changes.

• Fixes Load global config from /etc/wp-cli/ if it exists #5088

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.