Document HTTP proxy configuration for WP-CLI and WordPress core

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",

guides.md

@@ -11,4 +11,5 @@
 * **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advice
 * **[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

guides/http-proxy.md

@@ -0,0 +1,198 @@
+# 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. WP-CLI has no HTTP proxy setting of its own, but when PHP's cURL extension sends a request, cURL reads some standard proxy environment variables itself: HTTPS requests go through a proxy set in `https_proxy` or `HTTPS_PROXY`, and hosts listed in `no_proxy` or `NO_PROXY` connect directly.
+
+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 WordPress core requests and WP-CLI's own HTTP requests), 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 configures the proxy for both WordPress core HTTP requests and WP-CLI's own HTTP requests made through `WP_CLI\Utils\http_request()`, such as `wp core verify-checksums`.
+
+> 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:@stable
+```
+
+If the machine can reach the internet only through the proxy, set `https_proxy` when you run this command and any other `wp package` command (see Limitations below):
+
+```bash
+https_proxy=http://proxy.example.com:8080 wp package install ekamran/wp-cli-http-proxy-command:@stable
+```
+
+### 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"
+```
+
+> 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`:
+
+```yaml
+http-proxy:
+  env: true
+```
+
+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). The package does not read `NO_PROXY` or `no_proxy`, but cURL still does, so a host listed there skips the proxy configured by this package as well. To keep bypass rules in your WP-CLI configuration, list those hosts in `bypass-hosts`.
+
+### 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
+<?php
+$proxy_host = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );
+
+if ( ! $proxy_host ) {
+	return;
+}
+
+$proxy_url = parse_url( $proxy_host );
+
+if ( ! is_array( $proxy_url ) || empty( $proxy_url['host'] ) ) {
+	return;
+}
+
+$proxy_port = ! empty( $proxy_url['port'] ) ? (int) $proxy_url['port'] : null;
+
+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', rawurldecode( $proxy_url['user'] ) );
+}
+
+if ( ! empty( $proxy_url['pass'] ) ) {
+	define( 'WP_PROXY_PASSWORD', rawurldecode( $proxy_url['pass'] ) );
+}
+
+if ( ! defined( 'WP_PROXY_BYPASS_HOSTS' ) ) {
+	define( 'WP_PROXY_BYPASS_HOSTS', 'localhost, 127.0.0.1' );
+}
+```
+
+2. Require this file in your `wp-cli.yml` or `~/.wp-cli/config.yml`:
+
+```yaml
+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 only defines the constants that WordPress core uses for its own HTTP requests. WP-CLI's own HTTP requests do not use them. To route those through the proxy as well, use the [`ekamran/wp-cli-http-proxy-command`](https://github.com/ekamran/wp-cli-http-proxy-command) package. Neither approach covers `wp package` commands (see Limitations above).
+
+## 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.

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

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
 

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: