Skip to content

Forward environment variables to spawned processes in WP_CLI::launch() - #6166

Merged
swissspidy merged 5 commits into
wp-cli:mainfrom
manhphuc:fix/5362-forward-env-to-process
Mar 4, 2026
Merged

swissspidy merged 5 commits into
wp-cli:mainfrom
manhphuc:fix/5362-forward-env-to-process

Conversation

@manhphuc

Copy link
Copy Markdown
Contributor

Summary

This PR ensures that WP_CLI::launch() forwards environment variables to the spawned process so that child processes can still access configuration defined via getenv() / $_ENV (for example DB_NAME, DB_USER, and DB_PASSWORD inside wp-config.php).

Previously, WP_CLI::launch() always called Process::create( $command ) without passing an environment array. In environments where WordPress DB credentials (and other settings) are provided exclusively through environment variables (common in Docker setups), a child process spawned via WP_CLI::launch() would not see those variables, leading to database connection errors similar to issue #5362.

What this change does

  • Reads the current environment from $_ENV.
  • When $_ENV is not empty, calls:
    • Process::create( $command, null, $env );
      so the spawned process inherits the parent environment.
  • When $_ENV is empty, falls back to the previous behaviour:
    • Process::create( $command );
      to avoid affecting setups that rely on default environment propagation.

Rationale and backward compatibility

  • Fixes the scenario described in Database connection error caused by unset env vars in process #5362 where a WP_CLI::launch_self() call (and other usage of launch()) would fail with “Error establishing a database connection” because DB_* variables were not passed to child processes.
  • Maintains backward compatibility by:
    • Only passing an explicit env array when $_ENV is non-empty.
    • Preserving previous behaviour for systems where $_ENV is empty.

Testing

Manual testing performed inside a Docker-based environment:

  1. Installed WordPress using env-based DB configuration (DB_NAME, DB_USER, DB_PASSWORD, etc.) and wp-config.php reading them via getenv().

  2. Confirmed core commands behave normally:

    export HTTP_HOST=localhost
    /wp-cli-src/bin/wp core version --allow-root
    /wp-cli-src/bin/wp plugin list --allow-root
    /wp-cli-src/bin/wp db tables --allow-root

    All commands executed successfully.

  3. Verified that child processes now propagate the environment correctly, resolving the issue outlined in Database connection error caused by unset env vars in process #5362.

Related issue

@manhphuc
manhphuc requested a review from a team as a code owner December 10, 2025 14:35
@gemini-code-assist

This comment was marked as resolved.

@codecov

codecov Bot commented Dec 10, 2025 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
php/class-wp-cli.php 75.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

gemini-code-assist[bot]

This comment was marked as resolved.

@swissspidy

Copy link
Copy Markdown
Member

Thanks a lot for your PR! I know you've already tested this manually but would it be possible to add some Behat tests for this as well?

@manhphuc

Copy link
Copy Markdown
Contributor Author

Thanks a lot for the review and the kind words! 🙌

Yes, adding Behat coverage makes sense here.

My plan is to:

  • Add a scenario that verifies the forwarded environment variables are available to the child process started via WP_CLI::launch().
  • Add a scenario where $_ENV is initially empty and confirm that the fallback still forwards environment variables correctly.

I’ll update the PR with these Behat tests and ping you once they’re pushed.

@manhphuc
manhphuc force-pushed the fix/5362-forward-env-to-process branch from 294d238 to 784e373 Compare December 11, 2025 01:21
@manhphuc

manhphuc commented Dec 11, 2025 •

Copy link
Copy Markdown
Contributor Author

Hi @swissspidy! 👋

Quick update — I’ve just pushed the Behat coverage we discussed. 😊

The new feature file is:
features/launch-env-forwarding.feature

It includes two scenarios that directly exercise the behaviour of WP_CLI::launch() when forwarding environment variables to spawned processes:

  1. Scenario: Forwards environment variables when $_ENV is populated

    • The parent shell sets WPCLI_ENV_FWD=ok
    • WP_CLI::launch( "php env-dump.php", true, true ) is used to capture the child process output
    • We echo $result->stdout so Behat can assert that the spawned PHP process receives the environment variable via getenv()
  2. Scenario: Still forwards env vars when $_ENV is empty

    • PHP is invoked with variables_order=GPCS, meaning "E" is omitted and $_ENV may be empty
    • Even in this case, WP_CLI::launch() should fall back to inheriting the OS-level environment
    • The test confirms that the child process still receives WPCLI_ENV_FWD=ok

Both scenarios are passing locally with:

vendor/bin/behat --profile=default --colors features/launch-env-forwarding.feature

Here is a screenshot of the passing test run:

Screenshot 2025-12-11 at 13 58 16

Please let me know if you'd like any adjustments to the wording, structure, or coverage — happy to update anything! 🙌

@swissspidy
swissspidy requested review from a team and schlessera January 20, 2026 20:18

This comment was marked as resolved.

@swissspidy
swissspidy merged commit 5a0bdbe into wp-cli:main Mar 4, 2026
68 checks passed
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.

Database connection error caused by unset env vars in process

3 participants