Configuring PHP Composer Behind HTTP Proxy: A Comprehensive Guide

Understanding Composer Connection Issues in Proxy Environments

In restricted network environments where internet access is only available through HTTP or SOCKS proxies, developers using PHP Composer often encounter connection failures when attempting to access HTTPS URLs. The error message file could not be downloaded: failed to open stream: Cannot connect to HTTPS server through proxy typically indicates that the proxy server is not properly handling HTTPS CONNECT requests.

Core Mechanisms of Environment Variable Configuration

Composer relies on underlying HTTP clients (typically cURL or PHP stream contexts) to handle network requests. When HTTP_PROXY and HTTPS_PROXY environment variables are set, these clients automatically route traffic through the specified proxy servers. However, HTTPS connections require establishing a tunnel via the CONNECT method, which demands proper proxy server support and configuration.

The critical environment variables HTTP_PROXY_REQUEST_FULLURI and HTTPS_PROXY_REQUEST_FULLURI control the format of proxy requests. When set to 0 or false, clients send relative paths instead of full URLs, enhancing compatibility with certain proxy server implementations. Below are configuration methods for different systems:

Cross-Platform Configuration Implementation

Linux/Unix/macOS Systems

On Unix-based systems, environment variables can be set through shell configuration files. Add the following to ~/.bashrc, ~/.zshrc, or /etc/profile:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY_REQUEST_FULLURI=0
export HTTPS_PROXY_REQUEST_FULLURI=0

For maximum compatibility, it's recommended to set both uppercase and lowercase versions of environment variables, as different applications may use different naming conventions. Execute source ~/.bashrc to apply changes immediately.

Windows System Configuration

In Windows environments, permanent environment variables can be set through system properties:

1. Open System Properties and select the Advanced tab
2. Click Environment Variables
3. Add the following variables to either User or System variables:
   • Variable: HTTP_PROXY, Value: http://proxy.example.com:8080
   • Variable: HTTPS_PROXY, Value: http://proxy.example.com:8080
   • Variable: HTTP_PROXY_REQUEST_FULLURI, Value: 0
   • Variable: HTTPS_PROXY_REQUEST_FULLURI, Value: 0

For temporary use, execute in Command Prompt: set HTTP_PROXY=http://proxy.example.com:8080 and set HTTPS_PROXY=http://proxy.example.com:8080.

Advanced Scenario: Microsoft Proxy Server Handling

When corporate networks utilize Microsoft proxy servers (such as ISA or TMG servers), an additional middleware layer may be necessary. CNTLM (CrypTo NTLM) proxy can serve as a local proxy, handling NTLM authentication and forwarding requests to the corporate proxy server.

Basic steps for installing and configuring CNTLM:

# Install CNTLM on Linux systems
sudo apt-get install cntlm  # Debian/Ubuntu
sudo yum install cntlm      # RHEL/CentOS

# Edit configuration file /etc/cntlm.conf
Username    your_username
Domain      your_domain
Password    your_password  # or use hashed value
Proxy       corporate.proxy.com:8080
Listen      3128           # local proxy port

After configuration, point Composer's environment variables to the local CNTLM proxy: export HTTP_PROXY=http://localhost:3128.

Verification and Troubleshooting

After configuration, verify proxy settings using the following methods:

# Test if environment variables are active
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Test connection using curl
curl -I https://packagist.org

If connection issues persist, investigate the following aspects:

• Correctness of proxy server address and port
• Authentication requirements for the proxy server
• Firewall rules allowing outbound connections
• Proxy server support for HTTPS CONNECT method

By properly configuring environment variables and understanding proxy工作机制, developers can successfully use Composer for PHP dependency management in various network-restricted environments.