Guzzle Laravel Package

Getting Started

Install via Composer: composer require guzzlehttp/guzzle. Start with the GuzzleHttp\Client for basic HTTP interactions—synchronous or asynchronous. The simplest first use case: fetching JSON from an API endpoint.

use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://api.example.com/users/123');
$data = json_decode($response->getBody(), true);

Key things to explore first:

• Client configuration (base URI, timeouts, headers) in the constructor or per-request options.
• PSR-7 compliance: responses and requests implement PSR-7 interfaces (getResponse(), getBody(), etc.).
• Async requests via sendAsync() or requestAsync() for non-blocking operations (requires handling promises).

Implementation Patterns

• Middleware for cross-cutting concerns: Add logging, retry logic, authentication (e.g., JWT, OAuth), or request transformation via middleware stacking. Example:

  $client = new Client([
      'handler' => HandlerStack::create()->push(Middleware::retry($retryDecider))
  ]);
  

• Per-request overrides: Pass options like ['json' => $payload], ['headers' => ['Authorization' => 'Bearer ...']], or ['sink' => $stream] to request(), get(), post(), etc.
• Batching requests: Use promises with Promise\Utils::all() or GuzzleHttp\Pool for concurrent requests:

  $pool = new Pool($client, $generators, [
      'concurrency' => 5,
      'fulfilled' => function ($response, $id) { /* handle */ },
      'rejected' => function ($reason, $id) { /* handle */ },
  ]);
  $promise = $pool->promise();
  $promise->wait();
  

• Integration with frameworks: Laravel uses Guzzle via Http::client() (Symfony HttpKernel-based), which wraps guzzlehttp/guzzle. In tests, mock responses via MockHandler and middleware.

Gotchas and Tips

• Middleware order matters: Push middleware in the order you want them applied during request creation (outer to inner). Middleware added later via push() wraps earlier ones.
• Stream rewinding: Body streams must be rewindable for retries. If using StringBody, wrap in Stream::factory($content)—it’s rewindable by default.
• Timeout pitfalls: connect_timeout (DNS + TCP handshake) and timeout (total request duration) are distinct—configure both explicitly for reliability.
• Async ≠ concurrent by default: Promises execute serially unless you use Pool or utils::unwrap() with a handler stack supporting concurrency (e.g., cURL multi).
• Debugging: Enable curl.debug or debug handler option to see raw HTTP. In Laravel, use dd($response->getStatusCode(), $response->getHeaders()).
• Configuration via environment: Use GuzzleHttp\Client with base_uri and inject config via dependency injection rather than hardcoding URLs.
• Backward compatibility: v7 is required for PHP 8+; older code using v6 may need updates to handle PSR-18 deprecations or middleware signatures.
• PSR-18 interoperability: ClientInterface from psr/http-client is fully supported—great for decoupling from Guzzle-specific APIs in public interfaces.