PHP Composer behind http proxy
When composer attempts to download packages, it expects to resolve HTTPS requests directly or through a standard CONNECT tunnel. If your network environment restricts internet access exclusively to HTTP proxies or SOCKS proxies, you will encounter the error file could not be downloaded: failed to open stream: Cannot connect to HTTPS server through proxy. This happens because PHP's cURL implementation, which Composer relies on for package resolution, does not automatically handle the CONNECT method required for HTTPS traffic when only an HTTP proxy is configured via environment variables.
To resolve this, you must explicitly instruct Composer (or the underlying PHP runtime) to use a SOCKS proxy or configure an HTTP proxy with tunneling support. The specific solution depends on whether your infrastructure provides a SOCKS proxy or if you are forced to route HTTPS through an HTTP proxy that supports tunneling.
Configuring a SOCKS Proxy
If your network allows access via a SOCKS proxy, this is the most robust solution. Unlike HTTP proxies that often block or mishandle HTTPS traffic without explicit configuration, SOCKS4 and SOCKS5 proxies act as generic forwarding agents that are agnostic to the application-layer protocol. They allow the underlying TCP connection to pass through unchanged, enabling the client to perform the necessary TLS handshake directly with the destination server.
You can configure Composer to use a SOCKS proxy by setting the http.proxy configuration option within your project's composer.json or globally in your environment. While http_proxy and https_proxy environment variables are standard for HTTP, they do not inherently tell cURL to use the CONNECT method for HTTPS if the proxy is strictly defined as an HTTP proxy.
Instead, set these environment variables:
export http_proxy=socks5://user@proxy-host:port
export https_proxy=socks5://user@proxy-host:port
Alternatively, you can configure this directly in composer.json:
{
"config": {
"http-proxy": "socks5://user@proxy-host:1080"
}
}
Once configured, run composer config --global http-proxy "socks5://..." to apply it system-wide. This approach bypasses the need for manual TLS configuration because the proxy simply forwards the raw TCP stream to the destination.
Handling HTTP Proxies with Tunneling
If your environment only provides an HTTP proxy (e.g., http://proxy-host:8080) and you must force HTTPS traffic through it, you are relying on the proxy to initiate a CONNECT tunnel. Modern HTTP proxies support this by accepting a CONNECT request and then acting as a blind pipe for the TLS session.
However, simply setting export http_proxy=http://proxy-host:8080 and export https_proxy=http://proxy-host:8080 often fails if the PHP cURL handler does not detect that the proxy supports tunneling or if the proxy configuration is incomplete. In such cases, you may need to explicitly tell Composer to use a specific proxy type or ensure that your HTTP client library (PECL curl) is up to date.
If you encounter issues where the standard environment variables do not work, check your PHP installation. Ensure that the curl extension is enabled and supports the necessary protocols. Additionally, some corporate proxies require specific headers or authentication methods that cURL must respect. You might need to pass the proxy credentials directly in the configuration:
{
"config": {
"http-proxy": "http://user:password@proxy-host:8080",
"https-proxy": "http://user:password@proxy-host:8080"
}
}
Troubleshooting and Limitations
A common pitfall is assuming that setting http_proxy and https_proxy environment variables is sufficient. While this works for many applications, Composer's internal logic sometimes requires the proxy to be explicitly defined in its configuration file if the environment variable detection fails or if the proxy type (HTTP vs SOCKS) is ambiguous.
Another issue arises when the proxy server itself blocks the CONNECT method or terminates SSL connections before forwarding them. If your organization uses a forward-proxy that does not support HTTPS tunneling, you cannot bypass this limitation without installing a local MITM certificate or using a different network path. Always verify with your network administrator whether the proxy supports TLS passthrough.
If you are managing multiple projects, consider creating a dedicated .env file for development environments to manage these proxies cleanly:
COMPOSER_HTTP_PROXY=http://user:pass@proxy.example.com:8080
COMPOSER_HTTPS_PROXY=http://user:pass@proxy.example.com:8080
Then load this into your shell or application context before running composer install. This keeps your global configuration clean and prevents accidental exposure of proxy credentials in version control if .env files are excluded from git.
