{"id":981,"date":"2026-10-02T22:16:10","date_gmt":"2026-10-02T19:16:10","guid":{"rendered":"https:\/\/mexela.com\/blog\/php-guzzle-proxy\/"},"modified":"2026-10-02T22:16:10","modified_gmt":"2026-10-02T19:16:10","slug":"php-guzzle-proxy","status":"publish","type":"post","link":"https:\/\/mexela.com\/blog\/php-guzzle-proxy\/","title":{"rendered":"PHP Guzzle Proxy: Authentication, NO_PROXY, Timeouts, and Debugging"},"content":{"rendered":"

Configure a Guzzle proxy with the proxy<\/code> request option: pass one proxy URI string when all supported destination schemes share a route, or an array with http<\/code>, https<\/code>, and no<\/code> keys when routing differs. Load credentials from protected configuration, preserve intended NO_PROXY<\/code> exceptions, set finite connection and total timeouts, and verify one authorized request before adding retries.<\/p>\n

Scope:<\/strong> this guide covers Guzzle 7 request options in a PHP application, including explicit proxy ownership, environment behavior, authentication, time budgets, and safe diagnostics. It does not cover raw PHP cURL options, reverse proxies, framework-specific service containers, or permission to access a destination. The Proxy Setup and Developer Guides hub<\/a> links to the adjacent client guides.<\/p>\n

Choose the right proxy request option shape<\/h2>\n

The maintained Guzzle proxy request option documentation<\/a> accepts either a string or an associative array. A string applies one proxy to all destination protocols handled by the request. An array can assign separate proxy URIs to HTTP and HTTPS destinations and a no<\/code> list of hosts that connect directly.<\/p>\n

Use the string form when the service has one deliberate egress route. Use the array form only when protocol routing or direct exceptions genuinely differ. More configuration is not automatically safer: an unused fallback proxy, stale bypass, or copied scheme split creates routes that the operator may not know exist.<\/p>\n

<?php\nuse GuzzleHttp\\Client;\n\n$proxyUri = getenv('APP_PROXY_URI');\nif (!is_string($proxyUri) || $proxyUri === '') {\n    throw new RuntimeException('APP_PROXY_URI is required');\n}\n\n$client = new Client();\n$response = $client->request('GET', 'https:\/\/api.example.invalid\/route-check', [\n    'proxy' => $proxyUri,\n    'connect_timeout' => 5.0,\n    'timeout' => 12.0,\n    'verify' => true,\n]);<\/code><\/pre>\n
The reserved .invalid<\/code> host makes the example non-operational until an approved endpoint is supplied. Keep the proxy option close to the client boundary during the first acceptance test. Once behavior is known, a framework container may inject a preconfigured client, but the route owner should remain explicit.<\/p>\n
Map HTTP and HTTPS destinations deliberately<\/h2>\n
The array keys describe the destination URI scheme. The proxy URI itself can still use the protocol supported by the gateway. An HTTPS destination commonly travels through an HTTP proxy by means of CONNECT; the fact that the destination uses TLS does not require a proxy URI labeled HTTPS.<\/p>\n
When both destination schemes should use the same gateway, duplicate values in a protocol map add no value. Prefer one string. When they must differ, create the array from validated configuration and add a test for each branch. Keep TLS verification enabled for the destination. A certificate failure identifies a trust, hostname, tunnel, or approved inspection issue and must not be hidden.<\/p>\n
Record the handler in use. Guzzle options ultimately depend on the selected handler, and the cURL and PHP stream handlers do not expose every feature identically. The official request-options page notes handler-specific limits for connection timeout and debugging. A reproducible support record includes PHP, Guzzle, handler, cURL, and OpenSSL versions where applicable.<\/p>\n
Decide whether environment variables or application code own routing<\/h2>\n
HTTP client stacks may inherit proxy environment variables through their handler and process environment. That can be convenient in a container whose deployment manifest owns egress, but it can also surprise application code that appears to have no proxy configuration. Inspect the launch environment without printing secret values and choose one ownership model.<\/p>\n
If deployment owns the route, document the lower- and uppercase variable forms supported by the environment, restart workers after a change, and perform the same acceptance request used by application-owned configuration. If PHP code owns the route, pass the request option explicitly and do not assume that unrelated shell settings are irrelevant.<\/p>\n
Configuration must fail closed when a proxy is mandatory. An empty host, malformed URI, missing secret reference, or ambiguous bypass should stop worker startup or reject the job. Silent direct fallback makes evidence unreliable and can violate network policy.<\/p>\n
Preserve the NO_PROXY bypass when setting an explicit option<\/h2>\n
A NO_PROXY<\/code> bypass is a direct-routing rule. Guzzle can populate bypass behavior from the environment, but the documentation warns that when code supplies an explicit proxy<\/code> request option, code is responsible for carrying the parsed NO_PROXY<\/code> value into the array’s no<\/code> key.<\/p>\n
That distinction matters during migrations. Replacing environment-owned routing with one explicit proxy string may discard an internal-host exception. Conversely, copying a broad bypass into every service may send public traffic directly. Parse a comma-separated value into trimmed, non-empty entries, validate the allowed host forms, and reject a wildcard when policy requires the gateway.<\/p>\n
Test one proxied host and one bypassed host independently. A successful response is not enough because both paths may reach the same destination. Compare the observed source route or use controlled network evidence. Review exceptions periodically and keep a reason, owner, and expiry or review date.<\/p>\n
Protect proxy authentication separately from destination credentials<\/h2>\n
Guzzle permits credentials in a proxy URI, but a complete URI is easy to leak through exception messages, configuration dumps, monitoring, shell history, or debug traces. Obtain the username and password from an approved secret source, validate them before building the runtime value, and never log the result.<\/p>\n
Proxy authentication and destination authorization are separate. An HTTP 407 indicates the gateway rejected or requested proxy credentials. A destination 401 usually concerns API credentials, while 403 and 429 belong to destination authorization or pacing. Preserve the response source before rotating any secret. The proxy authentication guide<\/a> explains username\/password access and IP allowlisting.<\/p>\n
Prefer a secret manager or deployment injection over a committed .env<\/code> file. Redact proxy-related URI user information from exception reporters. When credentials rotate, restart or refresh long-lived clients according to the application’s lifecycle and rerun the one-request check.<\/p>\n
Separate connection, total, and streamed-read timeouts<\/h2>\n
Guzzle’s connect_timeout<\/code> bounds the connection phase when the handler supports it. The general timeout<\/code> bounds the entire request. The default value documented for both can permit indefinite waiting, so an operational client should choose finite values based on its service budget rather than inherit infinity accidentally.<\/p>\n
A streamed response adds read_timeout<\/code>, which applies to individual reads when streaming is enabled. It is not a replacement for a total deadline. A short connection budget with a larger total budget distinguishes an unreachable gateway from a slow but connected destination. Record which limit fired rather than collapsing every transfer exception into \u201cproxy failed.\u201d<\/p>\n
Retries multiply time budgets. For a safe GET, cap attempts, use backoff and jitter, retain the first exception, and stop on authentication, certificate, or destination-policy errors. Do not automatically repeat a state-changing request unless the API contract and an idempotency key make repetition safe.<\/p>\n
Run one bounded route verification<\/h2>\n
    \n
  1. Record PHP, Guzzle, handler, cURL, and OpenSSL versions without secrets.<\/li>\n
  2. Choose an owned or approved endpoint that reports the source address it observes.<\/li>\n
  3. Send one direct request from the same worker when policy permits and record status and duration.<\/li>\n
  4. Enable exactly one explicit or environment-owned proxy route.<\/li>\n
  5. Send the same GET with finite connection and total timeouts.<\/li>\n
  6. Confirm the observed source matches the expected assignment and TLS remains valid.<\/li>\n
  7. Repeat once with the same reusable client.<\/li>\n
  8. Test one approved application endpoint at conservative volume.<\/li>\n<\/ol>\n
    Expected observation:<\/strong> the request reaches the selected proxy within the connection budget, completes within the total budget, validates destination TLS, and reports an exit different from the direct control. A second request through the same client should provide comparable route evidence without changing configuration.<\/p>\n
    The proxy verification guide<\/a> provides a wider direct-versus-proxied evidence sequence. Do not use a successful neutral check as proof of universal destination acceptance or application permission.<\/p>\n
    For a Node.js worker, use the Undici ProxyAgent guide<\/a> to verify the dispatcher separately. For a Python crawler, follow the Scrapy proxy middleware guide<\/a>; crawler retries and concurrency need their own limits even when the destination and proxy assignment are the same.<\/p>\n
    Use Guzzle troubleshooting evidence without leaking secrets<\/h2>\n
    Guzzle’s debug<\/code> option can write handler diagnostics to standard output or a supplied stream. With the cURL handler, verbose transfer information may include hosts, headers, or credentials. Never enable it indiscriminately in production logs. Capture the smallest failing request in a protected environment, direct output to a controlled stream, and sanitize before sharing.<\/p>\n\n\n\n\n\n\n\n\n\n\n
    Observation<\/th>\nBoundary<\/th>\nFirst check<\/th>\n<\/tr>\n<\/thead>\n
    Proxy host cannot resolve<\/td>\nDNS or configuration<\/td>\nValidate the redacted host and worker resolver<\/td>\n<\/tr>\n
    Connection refusal or timeout<\/td>\nGateway reachability<\/td>\nCheck protocol, port, firewall, and connect budget<\/td>\n<\/tr>\n
    HTTP 407<\/td>\nProxy authentication<\/td>\nCheck gateway account and secret rotation<\/td>\n<\/tr>\n
    Certificate exception<\/td>\nTunnel or TLS<\/td>\nKeep validation enabled and inspect hostname and issuer<\/td>\n<\/tr>\n
    HTTP 401, 403, or 429<\/td>\nDestination<\/td>\nReview API authorization, policy, and pacing<\/td>\n<\/tr>\n
    Unexpected direct route<\/td>\nOwnership or bypass<\/td>\nInspect explicit options, environment values, and the no list<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Catch the narrow Guzzle exception classes needed by the application and preserve their causal chain privately. Log a route label, destination category, status class, timeout stage, elapsed time, and correlation identifier. Omit complete URIs, authorization headers, cookies, request bodies, response bodies, and customer identifiers.<\/p>\n
    Keep configuration reproducible across queue workers, web processes, scheduled jobs, and command-line maintenance scripts. Record which service definition injects the route, which handler the installed client selects, and which deployment version owns the bypass list. A request that succeeds in a console can still fail in a worker started with another environment, CA bundle, DNS resolver, or PHP configuration. Compare those inputs before replacing the endpoint. Add a startup health check that validates non-secret structure without sending customer traffic, then run the controlled route request after deployment. Store only the result class, timing, and opaque route label so operational evidence does not become a credential leak.<\/p>\n
    Operational limits:<\/strong> one successful Guzzle request proves one PHP runtime, handler, proxy route, destination, and moment. It does not prove another worker inherited the same environment, that every destination accepts the exit, or that future latency and availability will match. A proxy changes routing; it does not grant permission or remove API limits.<\/p>\n
    Choose the plan after the PHP client passes<\/h2>\n
    Document the required protocol, stable-session behavior, location, authentication, concurrency, transfer estimate, worker lifecycle, and acceptance request. When the service needs an endpoint assigned only to its team for repeatable API calls or allowlisting, compare those measured requirements with current Mexela private proxy options<\/a> and confirm current inventory.<\/p>\n
    Frequently asked questions<\/h2>\n
    \n
    Can Guzzle use one proxy for every request scheme?<\/h3>\n
    Yes. Pass a proxy URI string when the same route applies. Use the array form only when HTTP, HTTPS, or direct exceptions differ.<\/p>\n
    Why did my NO_PROXY behavior disappear?<\/h3>\n
    When code supplies the proxy request option, it must carry the parsed bypass hosts into the array’s no key. Test the direct exception explicitly.<\/p>\n
    What is the difference between connect_timeout and timeout?<\/h3>\n
    The connection option bounds the connect phase when supported; the general timeout bounds the complete request. Stream reads can have an additional read timeout.<\/p>\n
    Should debug output be enabled in production?<\/h3>\n
    Not in general logs. Handler diagnostics may expose sensitive details. Capture a minimal trace privately, redact it, then disable debug output.<\/p>\n
    Does an HTTP 407 mean the API key is wrong?<\/h3>\n
    No. It is a proxy authentication response. Destination authentication is a separate boundary, commonly represented by 401 or an application-specific response.<\/p>\n
    Can I disable certificate checks to test the route?<\/h3>\n
    No. Keep verification enabled. A certificate error is diagnostic evidence about trust, hostname, tunneling, or an approved inspection layer.<\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
    Configure Guzzle with one proxy or protocol-specific routes, preserve NO_PROXY bypasses, protect credentials, bound timeouts, and debug failures safely.<\/p>\n","protected":false},"author":0,"featured_media":982,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[189],"tags":[],"_links":{"self":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/981"}],"collection":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/comments?post=981"}],"version-history":[{"count":0,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/981\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/media\/982"}],"wp:attachment":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/media?parent=981"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/categories?post=981"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/tags?post=981"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}