Http Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require guzzlehttp/guzzle
   

   (Note: The package mentioned is a legacy reference to Guzzle 3, but the modern equivalent is guzzlehttp/guzzle for Guzzle 6/7.)

2. First Request

   use GuzzleHttp\Client;
   
   $client = new Client();
   $response = $client->get('https://api.example.com/data');
   $body = $response->getBody()->getContents();
   

3. Key Files

   • Guzzle Documentation
   • vendor/guzzlehttp/guzzle/src/ (Core classes)
   • config/guzzle.php (If using Laravel’s HTTP client wrapper)

First Use Case

Fetching JSON from an API

$response = $client->request('GET', 'https://api.example.com/users', [
    'headers' => ['Accept' => 'application/json'],
]);
$data = json_decode($response->getBody(), true);

Implementation Patterns

Common Workflows

1. Reusable Clients

   // In a service provider or config
   $client = new Client([
       'base_uri' => 'https://api.example.com/v1/',
       'timeout'  => 10.0,
       'headers'  => ['User-Agent' => 'MyApp/1.0'],
   ]);
   

2. Middleware for Logging/Modifying Requests

   use GuzzleHttp\Middleware;
   
   $stack = HandlerStack::create();
   $stack->push(Middleware::tap(function ($request) {
       // Log request details
       logger()->debug('API Request:', ['url' => $request->getUri()]);
   }));
   
   $client = new Client(['handler' => $stack]);
   

3. Async Requests

   $promises = [];
   foreach ($urls as $url) {
       $promises[] = $client->getAsync($url);
   }
   $results = GuzzleHttp\Promise\Utils::settle($promises)->wait();
   

4. Laravel Integration

   // Using Laravel's HTTP facade (wraps Guzzle)
   $response = Http::withOptions(['timeout' => 5])
       ->get('https://api.example.com/data');
   

Best Practices

• Use Client instances for connection pooling (avoid recreating per request).
• Leverage RequestOptions for headers, auth, and timeouts.
• Handle responses with getBody(), getStatusCode(), or json() helper.
• Stream large responses to avoid memory issues:

  $client->get('https://large-file.example.com', [
      'sink' => 'file://local-path'
  ]);
  

Gotchas and Tips

Pitfalls

1. Deprecations in Guzzle 7

   • getBody()->read() → Use getBody()->getContents().
   • send() → Use request() or get()/post().
   • createRequest() → Use createRequest() (still valid, but prefer request()).

2. Timeout Handling

   • Default timeout is no timeout (blocking). Always set:

     'timeout' => 5.0, // 5 seconds
     'connect_timeout' => 2.0,
     

3. SSL Issues

   • Disable verification only for testing:

     'verify' => false, // ⚠️ Avoid in production
     

   • For self-signed certs, use:

     'verify' => '/path/to/cert.pem',
     

4. Memory Leaks

   • Close streams after use:

     $response->getBody()->close();
     

   • Avoid storing responses unnecessarily (use iterators for large data).

5. Laravel-Specific Quirks

   • Laravel’s Http facade resets state between requests (unlike raw Guzzle).
   • For persistent configs, use a custom client:

     Http::macro('customClient', function () {
         return new Client(['base_uri' => config('services.api.base_uri')]);
     });
     

Debugging Tips

• Enable Guzzle Debug Middleware:

  $stack->push(Middleware::history());
  $history = $stack->getHandler()->getHistory();
  

• Check HTTP Status Codes:

  if ($response->getStatusCode() === 401) {
      // Handle unauthorized
  }
  

• Inspect Headers:

  $headers = $response->getHeaders();
  

Extension Points

1. Custom Handlers
   • Implement GuzzleHttp\Handler\HandlerInterface for proxy logic.
2. Plugins
   • Use GuzzleHttp\Plugin\PluginInterface to add features (e.g., retry logic).
3. PSR-7 Compliance
   • Guzzle uses PSR-7 messages. Extend GuzzleHttp\Psr7 classes for custom requests/responses.
4. Event Subscribers

   $client->getEmitter()->attach(
       'request.error',
       function ($event) { /* Handle errors */ }
   );