119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# How to use Composer behind a proxy
|
|
|
|
Composer, like many other tools, uses environment variables to control the use of a proxy server and
|
|
supports:
|
|
|
|
- `http_proxy` - the proxy to use for HTTP requests
|
|
- `https_proxy` - the proxy to use for HTTPS requests
|
|
- `CGI_HTTP_PROXY` - the proxy to use for HTTP requests in a non-CLI context
|
|
- `no_proxy` - domains that do not require a proxy
|
|
|
|
These named variables are a convention, rather than an official standard, and their evolution and
|
|
usage across different operating systems and tools is complex. Composer prefers the use of lowercase
|
|
names, but accepts uppercase names where appropriate.
|
|
|
|
## Usage
|
|
|
|
Composer requires specific environment variables for HTTP and HTTPS requests. For example:
|
|
|
|
```
|
|
http_proxy=http://proxy.com:80
|
|
https_proxy=http://proxy.com:80
|
|
```
|
|
|
|
Uppercase names can also be used.
|
|
|
|
### Non-CLI usage
|
|
|
|
Composer does not look for `http_proxy` or `HTTP_PROXY` in a non-CLI context. If you are running it
|
|
this way (i.e. integration into a CMS or similar use case) you must use `CGI_HTTP_PROXY` for HTTP
|
|
requests:
|
|
|
|
```
|
|
CGI_HTTP_PROXY=http://proxy.com:80
|
|
https_proxy=http://proxy.com:80
|
|
|
|
# cgi_http_proxy can also be used
|
|
```
|
|
|
|
> **Note:** CGI_HTTP_PROXY was introduced by Perl in 2001 to prevent request header manipulation and
|
|
was popularized in 2016 when this vulnerability was widely reported: https://httpoxy.org
|
|
|
|
## Syntax
|
|
|
|
Use `scheme://host:port` as in the examples above. Although a missing scheme defaults to http and a
|
|
missing port defaults to 80/443 for http/https schemes, other tools might require these values.
|
|
|
|
The host can be specified as an IP address using dotted quad notation for IPv4, or enclosed in
|
|
square brackets for IPv6.
|
|
|
|
### Authorization
|
|
|
|
Composer supports Basic authorization, using the `scheme://user:pass@host:port` syntax. Reserved url
|
|
characters in either the user name or password must be percent-encoded. For example:
|
|
|
|
```
|
|
user: me@company
|
|
pass: p@ssw$rd
|
|
proxy: http://proxy.com:80
|
|
|
|
# percent-encoded authorization
|
|
me%40company:p%40ssw%24rd
|
|
|
|
scheme://me%40company:p%40ssw%24rd@proxy.com:80
|
|
```
|
|
|
|
> **Note:** The user name and password components must be percent-encoded individually and then
|
|
combined with the colon separator. The user name cannot contain a colon (even if percent-encoded),
|
|
because the proxy will split the components on the first colon it finds.
|
|
|
|
## HTTPS proxy servers
|
|
|
|
Composer supports HTTPS proxy servers, where HTTPS is the scheme used to connect to the proxy, but
|
|
only from PHP 7.3 with curl version 7.52.0 and above.
|
|
|
|
```
|
|
http_proxy=https://proxy.com:443
|
|
https_proxy=https://proxy.com:443
|
|
```
|
|
|
|
## Bypassing the proxy for specific domains
|
|
|
|
Use the `no_proxy` (or `NO_PROXY`) environment variable to set a comma-separated list of domains
|
|
that the proxy should **not** be used for.
|
|
|
|
```
|
|
no_proxy=example.com
|
|
# Bypasses the proxy for example.com and its sub-domains
|
|
|
|
no_proxy=www.example.com
|
|
# Bypasses the proxy for www.example.com and its sub-domains, but not for example.com
|
|
```
|
|
|
|
A domain can be restricted to a particular port (e.g. `:80`) and can also be specified as an IP
|
|
address or an IP address block in CIDR notation.
|
|
|
|
IPv6 addresses do not need to be enclosed in square brackets, like they are for
|
|
http_proxy/https_proxy values, although this format is accepted.
|
|
|
|
Setting the value to `*` will bypass the proxy for all requests.
|
|
|
|
> **Note:** A leading dot in the domain name has no significance and is removed prior to processing.
|
|
|
|
## Deprecated environment variables
|
|
|
|
Composer originally provided `HTTP_PROXY_REQUEST_FULLURI` and `HTTPS_PROXY_REQUEST_FULLURI` to help
|
|
mitigate issues with misbehaving proxies. These are no longer required or used.
|
|
|
|
## Requirement changes
|
|
|
|
Composer <2.8 used `http_proxy` for both HTTP and HTTPS requests if `https_proxy` was not set,
|
|
but as of Composer 2.8.0 it requires [scheme-specific](#usage) environment variables.
|
|
|
|
The reason for this change is to align Composer with current practice across other popular tools. To help
|
|
with the transition, as of Composer 2.7.3 the original behaviour remains but a warning message is
|
|
shown instructing the user to add an `https_proxy` environment variable.
|
|
|
|
To prevent the original behaviour during the transition period, set an empty environment variable
|
|
(`https_proxy=`).
|