Skip to content

Add environment variable configuration support to wp-cli.yml #6169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Copilot wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Add environment variable configuration support to wp-cli.yml #6169

Copilot wants to merge 7 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Dec 14, 2025 •
edited
Loading

Description

Adds support for configuring environment variable fallback values in wp-cli.yml. When an environment variable like WP_CLI_CACHE_DIR is not set in the shell, WP-CLI now checks the config file. Actual environment variables always take precedence.

Changes

Core implementation:

  • Added env configuration key to config-spec.php for defining environment variable fallbacks
  • Created WP_CLI\Utils\get_env_or_config() helper that checks environment first, then config
  • Updated environment variable reads to use the helper:
    • get_cache_dir() for WP_CLI_CACHE_DIR
    • Cache initialization for WP_CLI_CACHE_EXPIRY and WP_CLI_CACHE_MAX_SIZE
    • Package directory resolution for WP_CLI_PACKAGES_DIR

Documentation:

  • Updated JSON schema (wp-cli-config.json) with env property definition
  • Added example configuration to wp-cli.example.yml

Tests:

  • Added Behat scenarios verifying config fallbacks work correctly for all supported environment variables:
    • WP_CLI_CACHE_DIR
    • WP_CLI_PACKAGES_DIR
    • WP_CLI_CACHE_EXPIRY
    • WP_CLI_CACHE_MAX_SIZE
  • Added test scenarios confirming environment variables override config values
  • Added test scenarios verifying environment variable precedence behavior

Example Usage

env:
  WP_CLI_CACHE_DIR: /tmp/custom-cache
  WP_CLI_PACKAGES_DIR: /tmp/custom-packages
  WP_CLI_CACHE_EXPIRY: 3600
  WP_CLI_CACHE_MAX_SIZE: 104857600

Running wp cli info will use these values when the corresponding environment variables are not set.

How has this been tested?

  • All existing static analysis passes (lint, phpcs, phpstan)
  • Manual testing confirms both config fallbacks and environment variable precedence
  • Comprehensive Behat test coverage for all supported environment variables
  • Tests verify both config fallback and environment variable override behavior

Checklist:

  • Functional tests have been added
  • Documentation has been updated as necessary
Original prompt

This section details on the original issue you should resolve

<issue_title>Ability to set environment variables in wp-cli.yml</issue_title>
<issue_description>Sometimes environment variables (https://make.wordpress.org/cli/handbook/references/config/#environment-variables) are not available in the shell for wp-cli, and thus it would be nice to be able to set these in wp-cli.yml

Example would be to configure WP_CLI_CACHE_DIR etc. using the wp-cli.yml file.</issue_description>

Comments on the Issue (you are @copilot in this section)

@danielbachhuber Thanks for the suggestion, @tomsommer

I'd be open to this if someone wants to submit a pull request!

To clarify the implementation: we wouldn't want to have wp-cli.yml set environment variables. Rather, we'd want to update WP-CLI to check wp-cli.yml for a value if the corresponding environment variable wasn't set.

Sometimes environment variables are not available in the shell for wp-cli

For posterity, could you provide a bit more detail as to when this isn't the case?

@danielbachhuber Related https://github.com//issues/6130 @swissspidy Related: #5645

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 3 commits December 14, 2025 21:02
@swissspidy
Add support for environment variables in wp-cli.yml
240eabc 
- Add 'env' configuration key to config-spec.php
- Create get_env_or_config() helper function in utils.php
- Update get_cache_dir() to use config fallback
- Update cache expiry/max_size to use config fallback
- Update packages_dir to use config fallback
- Add Behat tests for env variable configuration
- Environment variables still take precedence over config

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy
Update documentation and schema for env configuration
2734e2a 
- Add env example to wp-cli.example.yml
- Update JSON schema to include env property
- Document that env values are fallbacks when env vars not set

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
@swissspidy
Address code review feedback
abfdce2 
- Add null check for runner->config in get_env_or_config()
- Update schema description to clarify values are converted to strings
- Allow both string and numeric types in schema (YAML parses numbers)

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Copilot AI changed the title [WIP] Add ability to set environment variables in wp-cli.yml Add environment variable configuration support to wp-cli.yml Dec 14, 2025
Copilot AI requested a review from swissspidy December 14, 2025 21:10
@codecov
Copy link

codecov bot commented Dec 14, 2025 •
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

swissspidy
swissspidy reviewed Dec 14, 2025
View reviewed changes
swissspidy
swissspidy reviewed Dec 14, 2025
View reviewed changes
swissspidy
swissspidy reviewed Dec 14, 2025
View reviewed changes
swissspidy
swissspidy reviewed Dec 14, 2025
View reviewed changes
@swissspidy swissspidy requested a review from Copilot December 14, 2025 21:26
Copilot AI reviewed Dec 14, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR adds support for configuring environment variable fallback values in wp-cli.yml configuration files. When environment variables like WP_CLI_CACHE_DIR are not set in the shell, WP-CLI will now check the configuration file for fallback values. Actual environment variables always take precedence over config values.

  • Introduces a new env configuration key in wp-cli.yml for defining environment variable fallbacks
  • Implements a get_env_or_config() helper function that checks environment variables first, then config
  • Updates environment variable reads for cache directory, cache settings, and packages directory to use the new helper

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
php/config-spec.php Adds the env configuration specification with type <map> and documentation
php/utils.php Implements get_env_or_config() helper function and updates get_cache_dir() to use it
php/class-wp-cli.php Updates cache initialization to use get_env_or_config() for WP_CLI_CACHE_EXPIRY and WP_CLI_CACHE_MAX_SIZE
php/WP_CLI/Runner.php Updates packages directory resolution to use get_env_or_config() for WP_CLI_PACKAGES_DIR
schemas/wp-cli-config.json Adds JSON schema definition for the env property accepting strings and numbers
schemas/wp-cli.example.yml Adds example configuration showing how to use the env key
features/config.feature Adds Behat test scenarios verifying config fallback behavior and environment variable precedence

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@swissspidy
Add test coverage for WP_CLI_CACHE_EXPIRY and WP_CLI_CACHE_MAX_SIZE
e1eddeb 
- Add scenario testing WP_CLI_CACHE_EXPIRY configuration
- Add scenario testing WP_CLI_CACHE_MAX_SIZE configuration
- Add scenario testing environment variable precedence for both
- Tests verify config fallbacks and env var override behavior

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Copilot AI requested a review from swissspidy December 14, 2025 21:43
@swissspidy swissspidy marked this pull request as ready for review December 14, 2025 22:04
@swissspidy swissspidy requested a review from a team as a code owner December 14, 2025 22:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@swissspidy swissspidy Awaiting requested review from swissspidy

At least 1 approving review is required to merge this pull request.

Assignees

@swissspidy swissspidy

Copilot code review Copilot

Labels

command:cli command:config

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Ability to set environment variables in wp-cli.yml

2 participants

@swissspidy