Add FAQ about using a proxy (#11933)

doc/faqs/how-to-use-composer-behind-a-proxy.md

@@ -0,0 +1,118 @@
+# 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=`).