Guzzle Laravel Package

Technical Evaluation

Architecture Fit

• PSR-7/PSR-18 Compliance: Guzzle 7.14.1 remains fully compliant with PSR-7/PSR-18, ensuring seamless integration with Laravel’s HTTP stack (e.g., HttpClient facade, symfony/http-client). The updated guzzlehttp/psr7 constraint (^2.12.5) aligns with Laravel’s PSR-7 implementation (e.g., nyholm/psr7:^1.6 in Laravel 10+).
• Middleware System: Guzzle’s middleware architecture is unchanged, but fixes in 7.14.1 (e.g., proxy credential handling, cURL multi-handler stability) improve reliability for Laravel’s middleware pipeline. Example: Use GuzzleHttp\Middleware::tap() for observability alongside Laravel’s middleware.
• Transport Agnosticism: Guzzle 7.14.1 enhances async capabilities with fixes for cURL multi-handler blocking (e.g., #3500), making it safer for Laravel Queues + async HTTP calls (e.g., webhooks). The stream handler now rejects conflicting options (e.g., stream => true with capped handlers), reducing edge-case failures in Laravel’s file downloads.

Integration Feasibility

• Laravel HTTP Client Integration:
  • Breaking Changes: None for core Laravel integration. However, the rejection of raw cURL options conflicting with explicit multiplexing (e.g., CURLOPT_HTTPAUTH + NTLM) may require updates to custom HttpClient wrappers using low-level cURL options.
  • New Features: Leverage 7.14.1’s fixes for proxy credential redaction and cURL multi-handler stability to secure Laravel’s external API calls (e.g., behind corporate proxies).
  • Example Update:

    // Safe proxy configuration in Laravel's HttpClient
    $client = new \GuzzleHttp\Client([
        'proxy' => 'http://user:[email protected]',
        'handler' => \GuzzleHttp\HandlerStack::create(
            \GuzzleHttp\Middleware::retry(new \GuzzleHttp\RetryMiddleware(), [
                'max_retries' => 3,
            ])
        ),
    ]);
    

• Service Container: No changes to Guzzle’s DI compatibility. Bind custom clients to Laravel’s container as before:

  $this->app->bind(\GuzzleHttp\Client::class, fn () => new \GuzzleHttp\Client(config('guzzle.defaults')));
  

• Queue Workers: Fixes for cURL multi-handler blocking (e.g., #3498) make async requests more stable in Laravel Queues. Use sendAsync() for non-blocking calls:

  $promise = $client->getAsync('https://api.example.com/webhook');
  $promise->then(fn ($response) => Queue::dispatch(new ProcessWebhook($response)));
  

Technical Risk

• Proxy/Authentication Conflicts: Guzzle 7.14.1 tightens validation for proxy credentials and auth types (e.g., NTLM). Risk: Laravel apps using custom cURL options (e.g., CURLOPT_HTTPAUTH) may fail if combined with proxies. Mitigation:
  • Audit config/guzzle.php for raw cURL options.
  • Replace with Guzzle middleware (e.g., GuzzleHttp\Middleware::auth).
• Stream Handler Restrictions: The stream handler now rejects stream => true with capped handlers. Risk: Laravel’s file downloads (e.g., Http::download()) may fail if using custom stream handlers. Mitigation:
  • Test file downloads with Guzzle 7.14.1.
  • Fall back to Laravel’s default stream handling if needed.
• 32-bit Platforms: Fixes for integer overflow in cURL multi delays (e.g., #3502) may expose issues on legacy 32-bit PHP. Mitigation: Ensure PHP 7.4+ (64-bit) is used.
• Deprecations: No new deprecations, but the on_trailers callback is now validated earlier, which may affect custom middleware. Mitigation: Update middleware to handle trailer validation:

  $client->get('...', [
      'on_trailers' => fn (array $trailers) => logger()->info('Trailers', $trailers),
  ]);
  

Key Questions

1. Proxy Dependencies: Does the app use proxies with custom auth (e.g., NTLM)? If so, test Guzzle 7.14.1’s stricter validation (e.g., #3495).
2. Streaming APIs: Are any endpoints using stream => true with custom stream handlers? Verify compatibility with 7.14.1’s restrictions.
3. Async Workflows: How critical are async HTTP calls (e.g., webhooks)? The cURL multi-handler fixes in 7.14.1 improve stability but may require retesting.
4. Custom Middleware: Does the app use on_trailers or raw cURL options? Update middleware to comply with 7.14.1’s validation.
5. PHP Environment: Is the app running on 32-bit PHP? If so, test cURL multi delays under load (fixed in #3502).

Integration Approach

Stack Fit

• Laravel Core:
  • HTTP Client: Guzzle 7.14.1 integrates with Laravel’s HttpClient facade without changes. Use the facade’s custom macro to override defaults:

    Http::macro('secure', fn () => new \GuzzleHttp\Client([
        'timeout' => 30,
        'headers' => ['User-Agent' => 'Laravel/10'],
    ]));
    

  • Queues: Async fixes (e.g., #3498) make Guzzle safer for Laravel Queues. Example:

    $promise = Http::secure()->getAsync('https://api.example.com/data');
    $promise->then(fn ($response) => Queue::push(new ProcessData($response->getBody())));
    

  • Middleware: Leverage Guzzle’s middleware for cross-cutting concerns (e.g., logging, retries). Example:

    use GuzzleHttp\Middleware;
    
    $stack = Middleware::tap(fn ($request, $next) => logger()->info('Request', $request));
    $client = new \GuzzleHttp\Client(['handler' => HandlerStack::create($stack)]);
    

• Third-Party: Compatible with PSR-18 libraries (e.g., php-http/client-implementation) and Laravel packages like spatie/laravel-activitylog (for HTTP event logging).
• PHP Extensions: Requires curl (≥7.34.0) or openssl for HTTPS. Guzzle 7.14.1 defaults to cURL if available, with fallback to streams.

Migration Path

1. Assessment Phase:
   • Audit HTTP calls for:
     • Raw cURL options (e.g., CURLOPT_HTTPAUTH).
     • Custom stream handlers with stream => true.
     • Proxy configurations with NTLM/auth conflicts.
   • Test proxy-dependent APIs (e.g., corporate integrations).
2. Dependency Update:

   composer require guzzlehttp/guzzle:^7.14 --update-with-dependencies
   composer remove illuminate/http-guzzle  # If using Laravel's bundled Guzzle 6.x
   

3. Feature Parity:
   • Replace Http::withOptions() with Guzzle’s Client constructor.
   • Update middleware to handle on_trailers validation.
4. Testing:
   • Unit Tests: Use Guzzle’s MockHandler to test async workflows.

     use GuzzleHttp\Handler\MockHandler;
     use GuzzleHttp\Psr7\Response;
     
     $mock = new MockHandler([new Response(200)]);
     $client = new \GuzzleHttp\Client(['handler' => HandlerStack::create($mock)]);
     

   • Integration Tests: Test proxy/auth scenarios and file downloads.
   • Load Tests: Verify cURL multi-handler fixes under concurrent async requests.
5. Rollout:
   • Deploy to staging with Guzzle 7.14.1 behind a feature flag.
   • Monitor for proxy/auth failures or streaming issues.

Compatibility

• Laravel Versions:
  • Laravel 10/9: Full compatibility (PHP