Add HTTP proxy configuration example

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.

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?

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 :)

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.

That would be excellent, thank you!

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?

Sure, why not! Always good to have something runnable to verify the implementation, and this could be linked to from the docs as well.

I built a local package prototype and tested it.

My current read is that the package approach is the best first step: it keeps this opt-in, avoids a large copy/paste docs example, and avoids changing WP-CLI framework config before we know the shape is right.

One important detail from the prototype: installing the package alone should not trust proxy env vars. It should require explicit config, with env lookup only when users set something like env: true.

The local prototype supports config by url or host/port, optional auth, bypass hosts, WordPress core proxy constants, and WP-CLI HTTP requests via http_request_options.

Would you prefer that I clean this up as a package PR/repo next, or share the prototype first?

If you have a repo to share that would be great :)

Sure, I put the prototype here:

https://github.com/ekamran/wp-cli-http-proxy-command

It is still rough, but it shows the package direction with opt-in config and runnable status/check commands.

Awesome, thanks!

I just shared it in some of the related issues about this topic. Hopefully there will be some feedback :)

At first glance it would be cool if there were Behat test to verify that the command works as extended. Not sure how feasible it would be though.

But if the package works well, we can definitely simply link to that in the handbook.

I added a first Behat test suite to the prototype.

It now covers the opt-in config paths, env vars only when enabled, WordPress proxy constants, local proxy request handling, bypass hosts, and a clean error when the proxy is unreachable.

Local composer test is passing.

@swissspidy

Hello @swissspidy

Opened PR #658 for this.

Adds guides/http-proxy.md documenting:

Recommended setup via ekamran/wp-cli-http-proxy-command
Manual fallback for WordPress core proxy constants
Cross-links from config and troubleshooting docs

Please review it.

Thank you.

There's also #654, let's merge efforts of possible.

Not merging anything for now

@swissspidy

There's also #654, let's merge efforts of possible.

Not merging anything for now

Thanks @swissspidy Understood, happy to merge efforts with #654.

I compared both PRs. #658 adds cross-links in references/config.md and
guides/troubleshooting.md on top of the main guide. Let me know whether you'd
prefer I:

Push those extras into Document HTTP proxy configuration #654's branch, or
Keep Document HTTP proxy configuration for WP-CLI and WordPress core #658 open and incorporate any missing pieces from Document HTTP proxy configuration #654 here.

I'll wait for your direction before making further changes.

Navigation Menu

Repository navigation

Add HTTP proxy configuration example #601

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add HTTP proxy configuration example #601

Description

Activity

eddyd97-sudo commented on Dec 7, 2025

eddyd97-sudo commented on Dec 7, 2025

eddyd97-sudo commented on Dec 7, 2025

eddyd97-sudo commented on Dec 7, 2025

ekamran commented on May 24, 2026

swissspidy commented on May 25, 2026

ekamran commented on May 25, 2026

swissspidy commented on May 25, 2026

ekamran commented on May 25, 2026

swissspidy commented on May 25, 2026

ekamran commented on May 25, 2026

swissspidy commented on May 25, 2026

ekamran commented on May 25, 2026

swissspidy commented on May 25, 2026

ekamran commented on May 26, 2026

dilipom13 commented on Aug 2, 2026

swissspidy commented on Aug 2, 2026

dilipom13 commented on Aug 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions