From 253b3be8b2876deeead23a608148d65951b9b699 Mon Sep 17 00:00:00 2001 From: dilipom13 Date: Sun, 2 Aug 2026 13:06:48 +0530 Subject: [PATCH 1/2] Document HTTP proxy configuration for WP-CLI and WordPress core --- bin/handbook-manifest.json | 6 ++ guides.md | 1 + guides/http-proxy.md | 173 +++++++++++++++++++++++++++++++++++++ guides/troubleshooting.md | 2 + index.md | 1 + references/config.md | 4 + 6 files changed, 187 insertions(+) create mode 100644 guides/http-proxy.md diff --git a/bin/handbook-manifest.json b/bin/handbook-manifest.json index 7d7f782f..8366a802 100644 --- a/bin/handbook-manifest.json +++ b/bin/handbook-manifest.json @@ -371,6 +371,12 @@ "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/how-to-start-webserver.md", "parent": "how-to" }, + "http-proxy": { + "title": "HTTP Proxy Configuration", + "slug": "http-proxy", + "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/http-proxy.md", + "parent": "guides" + }, "identify-plugin-theme-conflict": { "title": "Identify a Plugin or Theme Conflict", "slug": "identify-plugin-theme-conflict", diff --git a/guides.md b/guides.md index bc7f19a9..37855058 100644 --- a/guides.md +++ b/guides.md @@ -11,4 +11,5 @@ * **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advise * **[Installing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/installing-packages/)** - Learn how to install packages and use version constraints * **[Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/)** - Some words about your environment +* **[HTTP Proxy Configuration](https://make.wordpress.org/cli/handbook/guides/http-proxy/)** - Configure an HTTP proxy for WP-CLI and WordPress core requests. * **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Some help to troubleshoot diff --git a/guides/http-proxy.md b/guides/http-proxy.md new file mode 100644 index 00000000..2bdf4dd7 --- /dev/null +++ b/guides/http-proxy.md @@ -0,0 +1,173 @@ +# HTTP Proxy Configuration + +When running WP-CLI in restricted network environments or behind corporate firewalls, you may need to route outbound HTTP/HTTPS requests through an HTTP proxy. + +WP-CLI and WordPress core use the Requests HTTP library for performing remote HTTP requests. By default, WP-CLI does not automatically read or trust proxy environment variables (such as `HTTP_PROXY` or `HTTPS_PROXY`). + +To configure an HTTP proxy for WP-CLI, you can use the community package [`ekamran/wp-cli-http-proxy-command`](https://github.com/ekamran/wp-cli-http-proxy-command) (recommended for full WP-CLI and WordPress proxy support), or manually configure WordPress core proxy constants in a bootstrap file. + +## Using the HTTP Proxy Package (Recommended) + +The [`ekamran/wp-cli-http-proxy-command`](https://github.com/ekamran/wp-cli-http-proxy-command) community package provides complete proxy support for both WP-CLI's internal HTTP requests (e.g. package management, updates) and WordPress core HTTP requests. + +> Note: The package requires WP-CLI 2.12.0 or newer. + +### Installation + +Install the package using the `wp package install` command: + +```bash +wp package install ekamran/wp-cli-http-proxy-command +``` + +### Configuration + +Add an `http-proxy` configuration block to your project's `wp-cli.yml` or your global `~/.wp-cli/config.yml` file: + +```yaml +http-proxy: + url: http://proxy.example.com:8080 +``` + +Scheme-less proxy URLs are also supported: + +```yaml +http-proxy: + url: proxy.example.com:8080 +``` + +Or configure the host and port separately: + +```yaml +http-proxy: + host: proxy.example.com + port: 8080 +``` + +### Authentication and Bypass Hosts + +If your proxy requires authentication or if specific hosts should bypass the proxy, specify them in the configuration: + +```yaml +http-proxy: + url: http://proxy.example.com:8080 + username: proxy-user + password: proxy-password + bypass-hosts: + - localhost + - 127.0.0.1 + - "*.local" + - "*.example.com" +``` + +### Using Environment Variables + +By default, proxy environment variables are not read automatically. To opt into reading proxy settings from your environment variables, set `env: true`: + +```yaml +http-proxy: + env: true +``` + +When `env: true` is set, the package checks the following environment variables in order: + +1. `HTTPS_PROXY` +2. `https_proxy` +3. `HTTP_PROXY` +4. `http_proxy` + +### Diagnostic Commands + +The package includes diagnostic commands to help verify your proxy configuration. + +Check the current proxy configuration status: + +```bash +wp http-proxy status +``` + +Perform a test HTTP request through WP-CLI's HTTP helper to verify connectivity: + +```bash +wp http-proxy check https://wordpress.org +``` + +### Behavior and Disabling + +When active, the package: + +- Automatically defines missing WordPress proxy constants (`WP_PROXY_HOST`, `WP_PROXY_PORT`, `WP_PROXY_USERNAME`, `WP_PROXY_PASSWORD`, `WP_PROXY_BYPASS_HOSTS`) after `wp-config.php` loads. +- Configures WP-CLI's internal HTTP requests by filtering `http_request_options`. +- Normalizes proxy URLs to Requests' `host:port` format. +- Applies `bypass-hosts` to both WordPress and WP-CLI HTTP requests. + +To temporarily disable the proxy without removing the package, set `enabled: false` in your YAML configuration: + +```yaml +http-proxy: + enabled: false +``` + +You can also bypass all installed packages for a single command invocation by passing the `--skip-packages` global flag: + +```bash +wp --skip-packages core update +``` + +### Limitations + +Composer-backed `wp package` commands, including `browse`, `list`, `install`, and `update`, use a separate HTTP client. Their network requests are not configured by this package. + +## Manual Configuration (WordPress Core Only) + +If you cannot install community packages or only need to configure proxy support for WordPress core HTTP requests, you can define the core proxy constants in a custom PHP file loaded via `wp-cli.yml`. + +1. Create a `proxy.php` file (e.g. in your project or home directory): + +```php + Note: This manual approach sets the constants used by WordPress core HTTP requests after WordPress loads, but does not automatically route WP-CLI's pre-bootstrap or standalone HTTP requests (such as `wp package` commands). For complete proxy coverage across all WP-CLI operations, use the [`ekamran/wp-cli-http-proxy-command`](https://github.com/ekamran/wp-cli-http-proxy-command) package. + +## Related Documentation + +* [Global parameters and configuration files](https://make.wordpress.org/cli/handbook/references/config/) — how `wp-cli.yml` and the `require` option work. +* [Installing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/installing-packages/) — package installation and version constraints. +* [Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/) — debugging network and configuration issues. diff --git a/guides/troubleshooting.md b/guides/troubleshooting.md index 840d58f7..4a5c6fe9 100644 --- a/guides/troubleshooting.md +++ b/guides/troubleshooting.md @@ -19,6 +19,8 @@ WP-CLI offers the command `wp --info`, which provides you with a lot of informat Before you start to debug issues, make sure you are using the latest version of WP-CLI. The latest version may already have solved an issue you experience. The command `wp cli update` will upgrade your WP-CLI version or confirm you already use the latest version. If the installation hangs, please ensure that you are allowed to connect to GitHub using SSL (port 443) and git (port 9418) for outbound connections. +If you are behind a corporate firewall or HTTP proxy, WP-CLI does not automatically use `HTTP_PROXY` or `HTTPS_PROXY` environment variables. See the [HTTP Proxy Configuration](https://make.wordpress.org/cli/handbook/guides/http-proxy/) guide for setup instructions. + ### What should I do if the WP-CLI output is different than expected? Before starting to investigate a bug, you should be aware of the factors that can change the default behavior of WP-CLI and how you can check whether they might be at the root of the issue. There are five main subsystems for modifying this default behavior: environment variables, configuration files, WP-CLI packages, `wp-config.php` file and WordPress extensions (plugins, themes, must-use plugins, drop-ins). diff --git a/index.md b/index.md index 8b526bd5..c6ea0cc7 100644 --- a/index.md +++ b/index.md @@ -20,6 +20,7 @@ Can’t find what you’re looking for? [Open an issue](https://github.com/wp-cl * **[Common issues and their fixes](https://make.wordpress.org/cli/handbook/guides/common-issues/)** - In case of fire, break glass. * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users. * **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Get help troubleshooting common WP-CLI issues. +* **[HTTP Proxy Configuration](https://make.wordpress.org/cli/handbook/guides/http-proxy/)** - Configure an HTTP proxy for WP-CLI and WordPress core requests. ### For developers diff --git a/references/config.md b/references/config.md index a09d1f39..85b338aa 100644 --- a/references/config.md +++ b/references/config.md @@ -358,6 +358,10 @@ By default, the `--context` flag was set to `cli` in the initial release (v2.6.0 If you are still using WP-CLI v2.6.0 but you want to use the default of `--context=auto`, you can do so by adding the necessary `context: auto` line to your global `wp-cli.yml` configuration file. Feel free to check the documentation on [WP-CLI configuration files](#config-files) if this is new to you. +## HTTP proxy configuration + +WP-CLI does not automatically read or trust proxy environment variables such as `HTTP_PROXY` or `HTTPS_PROXY`. To route outbound HTTP/HTTPS requests through a proxy, see the [HTTP Proxy Configuration](https://make.wordpress.org/cli/handbook/guides/http-proxy/) guide. + ## Environment variables WP-CLI's behavior can be changed at runtime through the use of environment variables: From 125b9fe5d72c4f37815bc1fef56917e378ff6744 Mon Sep 17 00:00:00 2001 From: dilipom13 Date: Sun, 2 Aug 2026 17:16:04 +0530 Subject: [PATCH 2/2] Address CodeRabbit review feedback on HTTP proxy guide Clarify credential handling, env var behavior, port requirements, URL-decoded auth values, and the extra-php fallback option. --- guides/http-proxy.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/guides/http-proxy.md b/guides/http-proxy.md index 2bdf4dd7..2a9a0cea 100644 --- a/guides/http-proxy.md +++ b/guides/http-proxy.md @@ -60,6 +60,8 @@ http-proxy: - "*.example.com" ``` +> Warning: Do not commit proxy credentials to source control. Use an untracked configuration file (for example `wp-cli.local.yml`), restrict file permissions, or inject credentials through your deployment environment. + ### Using Environment Variables By default, proxy environment variables are not read automatically. To opt into reading proxy settings from your environment variables, set `env: true`: @@ -69,13 +71,15 @@ http-proxy: env: true ``` -When `env: true` is set, the package checks the following environment variables in order: +When `env: true` is set, the package selects the **first non-empty** environment variable from this list and applies **one global proxy** for all requests: 1. `HTTPS_PROXY` 2. `https_proxy` 3. `HTTP_PROXY` 4. `http_proxy` +This differs from libcurl, which can use separate proxies per scheme (for example `http_proxy` for HTTP and `https_proxy` for HTTPS) and honors `NO_PROXY` / `no_proxy` for bypass rules. This package does **not** read `NO_PROXY` or `no_proxy`. If you rely on bypass rules from your environment, map those entries to `bypass-hosts` in your configuration instead. + ### Diagnostic Commands The package includes diagnostic commands to help verify your proxy configuration. @@ -138,18 +142,22 @@ if ( ! is_array( $proxy_url ) || empty( $proxy_url['host'] ) ) { return; } -define( 'WP_PROXY_HOST', $proxy_url['host'] ); +$proxy_port = ! empty( $proxy_url['port'] ) ? (int) $proxy_url['port'] : null; -if ( ! empty( $proxy_url['port'] ) ) { - define( 'WP_PROXY_PORT', $proxy_url['port'] ); +if ( null === $proxy_port ) { + $scheme = ! empty( $proxy_url['scheme'] ) ? $proxy_url['scheme'] : 'http'; + $proxy_port = ( 'https' === $scheme ) ? 443 : 80; } +define( 'WP_PROXY_HOST', $proxy_url['host'] ); +define( 'WP_PROXY_PORT', $proxy_port ); + if ( ! empty( $proxy_url['user'] ) ) { - define( 'WP_PROXY_USERNAME', $proxy_url['user'] ); + define( 'WP_PROXY_USERNAME', rawurldecode( $proxy_url['user'] ) ); } if ( ! empty( $proxy_url['pass'] ) ) { - define( 'WP_PROXY_PASSWORD', $proxy_url['pass'] ); + define( 'WP_PROXY_PASSWORD', rawurldecode( $proxy_url['pass'] ) ); } if ( ! defined( 'WP_PROXY_BYPASS_HOSTS' ) ) { @@ -164,6 +172,17 @@ require: - proxy.php ``` +Alternatively, when creating a new WordPress install, you can embed proxy constants in `wp-config.php` using `wp config create --extra-php`: + +```bash +wp config create --dbname=example --dbuser=root --dbpass=secret --extra-php <<'PHP' +define( 'WP_PROXY_HOST', 'proxy.example.com' ); +define( 'WP_PROXY_PORT', 8080 ); +PHP +``` + +This `extra-php` approach only applies to the generated `wp-config.php` at install time. It does not configure WP-CLI's own HTTP requests and is not suitable for existing installs unless you add the constants manually. + > Note: This manual approach sets the constants used by WordPress core HTTP requests after WordPress loads, but does not automatically route WP-CLI's pre-bootstrap or standalone HTTP requests (such as `wp package` commands). For complete proxy coverage across all WP-CLI operations, use the [`ekamran/wp-cli-http-proxy-command`](https://github.com/ekamran/wp-cli-http-proxy-command) package. ## Related Documentation