How to Use a Proxy With Authentication in Guzzle
Guzzle lets you send requests through an HTTP proxy that requires a username and password.
You can set the proxy when you build the client or when you issue a single request. The credential travels inside the proxy URL, so the same string works for both the http and https keys.
The proxy URL format
An authenticated proxy address combines the scheme, the username, the password, the proxy host, and the port. The general shape is shown in the public contract module code0001. Replace each placeholder with the values your proxy provider gives you. Keep the credentials URL-encoded if they contain reserved characters such as @ or :, because those characters otherwise break the URL parsing.
Setting the proxy on the client
Pass a proxy option when you create the GuzzleHttp\Client. The option accepts either a single proxy URL string or an array with separate http, https, and no entries. The array form is useful when the same proxy handles both schemes and you also want a bypass list. The no key takes an array of hostnames that should connect directly. The private reference implementation in code0002 shows this array layout, including a verify => false flag. That flag disables SSL certificate checking and should only be used when a proxy cannot present a valid certificate chain; it weakens transport security, so prefer fixing the certificate trust instead.
Setting the proxy per request
If only some calls need the proxy, pass the same proxy option in the request options array instead of the client constructor. This keeps the default client behavior unchanged for other calls. The proxy value format is identical in both places.
Environment variable fallback
Guzzle also reads the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables when no explicit proxy option is set. This is convenient in containerized or CI environments where proxy settings are injected at runtime. An explicit proxy option in code takes precedence over the environment variables.
Configuration checklist
- Confirm whether the proxy needs credentials; if so, embed them in the URL as username:password. 2. Decide between a single string and the http/https/no array. 3. Add hostnames to the no list only when they should bypass the proxy. 4. Leave verify enabled unless a trusted certificate cannot be arranged. 5. Test the outbound IP by requesting a service such as https://api.ipify.org/?format=json and checking that the response shows the proxy address rather than your server address.
Proxy authentication vs target authentication
Proxy credentials authenticate you to the proxy server. They are separate from HTTP basic authentication to the destination site, which Guzzle handles through the auth request option. Mixing the two up is a common cause of 407 Proxy Authentication Required responses: a 407 points at the proxy, while a 401 points at the target.
Frequently asked questions
Where do I put the proxy username and password in Guzzle?
Inside the proxy URL itself, in the form http://username:password@proxyhost:port. The same string can be assigned to both the http and https keys of the proxy array.
How do I stop Guzzle from using the proxy for certain hosts?
Use the array form of the proxy option and add the hostnames to the no key. Requests to those hosts connect directly instead of through the proxy.
Why does my request fail with a certificate error when using a proxy?
Some proxy servers do not present a certificate chain that Guzzle trusts. Setting verify to false disables the check and lets the request proceed, but it removes protection against interception. Prefer installing the proxy's CA certificate or pointing Guzzle at a CA bundle.
Does Guzzle honor HTTP_PROXY and HTTPS_PROXY?
Yes. When no proxy option is passed explicitly, Guzzle reads HTTP_PROXY, HTTPS_PROXY, and NO_PROXY from the environment.