Add HTTP proxy configuration documentation for WordPress core and WP-CLI

[Copilot]

Documents manual proxy configuration for both WordPress core HTTP requests and WP-CLI's own HTTP requests. WP-CLI doesn't honor HTTP_PROXY environment variable by default for security reasons.

Changes

• Added "HTTP proxy configuration" section to references/config.md
• Provides working examples using require config option to load proxy setup file
• Example reads HTTP_PROXY env var and sets WordPress proxy constants (WP_PROXY_HOST, WP_PROXY_PORT, WP_PROXY_USERNAME, WP_PROXY_PASSWORD)
• Includes validation for malformed URLs from parse_url()
• Adds configuration for WP-CLI's own HTTP requests using http_request_args hook to configure the Requests library

Examples

WordPress core HTTP requests only

wp-cli.yml:

require:
  - proxy.php

proxy.php:

<?php
$proxy_env = getenv( 'HTTP_PROXY' );

if ( ! $proxy_env ) {
	return;
}

$proxy_url = parse_url( $proxy_env );

if ( ! is_array( $proxy_url ) || ! isset( $proxy_url['host'] ) ) {
	return;
}

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

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

Both WordPress core and WP-CLI HTTP requests

proxy.php (extended):

<?php
$proxy_env = getenv( 'HTTP_PROXY' );

if ( ! $proxy_env ) {
	return;
}

$proxy_url = parse_url( $proxy_env );

if ( ! is_array( $proxy_url ) || ! isset( $proxy_url['host'] ) ) {
	return;
}

// Configure proxy for WordPress core HTTP requests
define( 'WP_PROXY_HOST', $proxy_url['host'] );

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

// Configure proxy for WP-CLI's own HTTP requests
if ( class_exists( 'WP_CLI' ) ) {
	$add_proxy_to_request = function( $r, $url ) use ( $proxy_env ) {
		$r['proxy'] = $proxy_env;
		return $r;
	};
	
	WP_CLI::add_hook( 'http_request_args', $add_proxy_to_request );
}

Usage:

# WordPress core HTTP requests (plugin updates)
$ HTTP_PROXY=http://proxy.example.com:8080 wp plugin update --all

# WP-CLI HTTP requests (package installation)
$ HTTP_PROXY=http://proxy.example.com:8080 wp package install wp-cli/doctor-command

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add HTTP proxy configuration example</issue_title>
<issue_description>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.</issue_description>

<agent_instructions>WP_Http_Proxy in WP core might serve as inspiration</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Add HTTP proxy configuration example #601

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[swissspidy]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds valuable documentation on configuring HTTP proxies for WP-CLI and WordPress core. The examples are clear and cover two important use cases. I've suggested a small improvement to the PHP examples to make them more robust by supporting HTTPS_PROXY and lowercase environment variables, which are common conventions.

[gemini-code-assist]

The current example only considers the HTTP_PROXY environment variable. It's a common practice to also support HTTPS_PROXY (for HTTPS requests) and lowercase variants (http_proxy, https_proxy).

Since WordPress Core doesn't differentiate between proxy settings for HTTP and HTTPS, it's best to prefer the HTTPS proxy variable if set, and fall back to the HTTP one. This makes the configuration more robust and aligns with user expectations.

Suggested change

	$proxy_env = getenv( 'HTTP_PROXY' );
	$proxy_env = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );

[gemini-code-assist]

The current example only considers the HTTP_PROXY environment variable. It's a common practice to also support HTTPS_PROXY (for HTTPS requests) and lowercase variants (http_proxy, https_proxy).

Since WordPress Core doesn't differentiate between proxy settings for HTTP and HTTPS, it's best to prefer the HTTPS proxy variable if set, and fall back to the HTTP one. This makes the configuration more robust and aligns with user expectations.

Suggested change

	$proxy_env = getenv( 'HTTP_PROXY' );
	$proxy_env = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );