Add HTTP proxy configuration example

[swissspidy]

Split out from wp-cli/core-command#292

• php-curl happens to honor the http_proxy env var
• Requests defers honoring that env var to the library user (e.g., WordPress core or WP-CLI) (see also Auto use Proxy if HTTP_PROXY & HTTPS_PROXY Environment variable is set WordPress/Requests#218)
• WP-CLI doesn't want to blindly trust that env var
• One should be able to manually configure proxy support via wp-cli.yml and the extra-php config

You might be able to do something like this:

# In wp-cli.yml
require:
  - path-to/proxy.php

// proxy.php

$proxy_host = getenv( 'HTTP_PROXY' );

if ( ! $proxy_host ) {
	return;
}

$proxy_url = parse_url( $proxy_host );

if ( $proxy_url['host'] ) {
	define( 'WP_PROXY_HOST', $proxy_url['host'] );
}

if ( $proxy_url['port'] ) {
	define( 'WP_PROXY_PORT', $proxy_url['port'] );
}

This would configure the proxy for HTTP requests in core when using WP-CLI, similar to when you define this in wp-config.php. The setup would be slightly more complex for modifying HTTP requests from WP-CLI itself.

[eddyd97-sudo]

#601

[eddyd97-sudo]

9945

[eddyd97-sudo]

Host

[eddyd97-sudo]

// proxy.php

$proxy_host = getenv( 'HTTP_PROXY' );

if ( ! $proxy_host ) {
return;
}

$proxy_url = parse_url( $proxy_host );

if ( $proxy_url['host'] ) {
define( 'WP_PROXY_HOST', $proxy_url['host'] );
}

if ( $proxy_url['port'] ) {
define( 'WP_PROXY_PORT', $proxy_url['port'] );
}

[ekamran]

I looked into this and also checked the existing draft PR #623 and the closed PR #636.

I think I can take a try at completing this, if that works for maintainers.

The main missing piece seems to be the WP-CLI-specific HTTP request handling. I verified locally that WP-CLI's own HTTP requests go through the http_request_options hook, not http_request_args. I also tested the Requests proxy format locally: normalizing an env value like http://127.0.0.1:8080 to 127.0.0.1:8080 works across the Requests proxy handling, while passing the raw URL can fail with the fsockopen transport.

My plan would be to document both cases:

• WordPress core HTTP requests using WP_PROXY_HOST, WP_PROXY_PORT, and optional auth constants.
• WP-CLI's own HTTP requests using WP_CLI::add_hook( 'http_request_options', ... ), with proxy env vars normalized to Requests' host:port format.

I would also include support for HTTPS_PROXY, https_proxy, HTTP_PROXY, and http_proxy, as suggested in the review on #623.

Would you be open to a fresh PR for this?

[swissspidy]

Appreciate the research & help!

I wanted to find some time to continue #623 for a while now. As you noticed, covering the settings for both types of HTTP requests involves quite some code. So I was tinkering with the idea of making this easier to use, for example through a new WP-CLI package or perhaps even some config in the framework itself. Then one doesn't have to copy all this stuff from documentation :)

[ekamran]

Thanks, that makes sense.

I agree that a long copy/paste proxy.php example in the docs may not be the best final user experience.

Would it be helpful if I first explore the possible directions and report back before opening a PR?

The options I can compare are:

• documenting the current manual setup,
• a small WP-CLI package that users can install/require,
• or a framework-level config approach if that is the direction you prefer.

I can do the investigation first and share a proposed path before writing the PR.

[swissspidy]

That would be excellent, thank you!

[ekamran]

I did another pass locally and found a cleaner path than a long docs-only example.

My current recommendation is to prototype a small WP-CLI package first, then add short handbook docs around that package if the direction looks good.

Reason: WP-CLI already keeps unknown config keys in extra_config, so a package can read a simple opt-in config block from wp-cli.yml without needing framework changes first.

Example config could be:

http-proxy:
  url: http://proxy.example.com:8080

or:

http-proxy:
  host: proxy.example.com
  port: 8080

I tested this locally with a package-style loader. The loader can read http-proxy from WP_CLI::get_runner()->extra_config, normalize the proxy into Requests' host:port format, define the WordPress core proxy constants, and hook WP-CLI's own HTTP requests through http_request_options.

The local checks covered:

• WordPress core constants: WP_PROXY_HOST, WP_PROXY_PORT, optional auth, and WP_PROXY_BYPASS_HOSTS.
• WP-CLI internal HTTP requests via WP_CLI::add_hook( 'http_request_options', ... ).
• url config and host / port config.
• URL-encoded proxy auth.
• fsockopen transport, where normalized host:port works.
• --skip-packages as an escape hatch.

So my updated read is that a small package is probably the best first step. It avoids asking users to copy a large proxy.php file from the docs, and it avoids a framework-level config change until maintainers decide this should become built in.

Would you prefer that I prototype the package approach first?