guzzle

Guzzle Best Practices

Guzzle is the de-facto PHP HTTP client. Use these rules to build robust, testable, and maintainable HTTP integrations.

1. Client Instantiation & Configuration

Always inject an immutable Guzzle client as a service. Configure it once with global defaults, especially timeouts.

✅ GOOD: Service-Oriented Client with Essential Defaults

<?php

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use Psr\Log\LoggerInterface;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\ConnectException;
use Exception;

final class MyApiClientFactory
{
    public static function create(LoggerInterface $logger): Client
    {
        $stack = HandlerStack::create();

        // 1. Logging: Log all requests and responses
        $stack->push(Middleware::log(
            $logger,
            new \GuzzleHttp\MessageFormatter(
                '{method} {uri} HTTP/{version} {code} {res_header_Content-Length}'
            )
        ));

        // 2. Retry Logic: Robust handling for transient errors (5xx, connection issues)
        $stack->push(Middleware::retry(
            function (
                $retries,
                RequestInterface $request,
                ResponseInterface $response = null,
                Exception $exception = null
            ) {
                // Limit to 3 retries
                if ($retries >= 3) {
                    return false;
                }
                // Retry on connection exceptions
                if ($exception instanceof ConnectException) {
                    return true;
                }
                // Retry on server errors (5xx)
                if ($response && $response->getStatusCode() >= 500) {
                    return true;
                }
                return false;
            },
            // Exponential backoff: 100ms, 200ms, 400ms
            function ($retries) {
                return 100 * (2 ** ($retries - 1));
            }
        ));

        return new Client([
            'base_uri' => 'https://api.example.com/v1/',
            'timeout' => 10.0,          // Total request timeout in seconds
            'connect_timeout' => 5.0,   // Connection timeout in seconds
            'headers' => [
                'Accept' => 'application/json',
                'User-Agent' => 'MyApp/1.0 (PHP Guzzle)',
            ],
            'handler' => $stack,
            'http_errors' => true,      // Throw exceptions for 4xx/5xx responses
        ]);
    }
}

// Usage in a service container or dependency injection
// $client = MyApiClientFactory::create($myLogger);
// $response = $client->get('users');