Buzz Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require kriswallsmith/buzz
   

   Buzz is dependency-free and requires PHP 7.4+.

2. First Request:

   use Buzz\Browser;
   use Buzz\Message\Request;
   
   $client = new Browser();
   $request = new Request('GET', 'https://api.example.com/users');
   $response = $client->send($request);
   
   echo $response->getBody();
   

3. Key Classes:

   • Browser: Main client for sending requests.
   • Request: Construct HTTP requests (GET, POST, etc.).
   • Message\Response: Handle responses (status, headers, body).

4. First Use Case: Fetch JSON data from an API:

   $response = $client->sendRequest('GET', 'https://api.example.com/data');
   $data = json_decode($response->getBody(), true);
   

Implementation Patterns

Common Workflows

1. REST API Integration

• Pattern: Use sendRequest() for simplicity or Request/Response objects for control.

  // Simple GET
  $response = $client->sendRequest('GET', 'https://api.example.com/users');
  
  // POST with JSON body
  $request = new Request('POST', 'https://api.example.com/users');
  $request->setBody(json_encode(['name' => 'John']));
  $request->setHeader('Content-Type', 'application/json');
  $response = $client->send($request);
  

• Laravel Integration: Use a service class to wrap Buzz for consistency:

  class ApiClient {
      protected $client;
  
      public function __construct(Browser $client) {
          $this->client = $client;
      }
  
      public function getUsers() {
          return $this->client->sendRequest('GET', config('services.api.users'));
      }
  }
  

2. Handling Responses

• Pattern: Check status codes and parse responses:

  $response = $client->sendRequest('GET', 'https://api.example.com/data');
  if ($response->getStatusCode() === 200) {
      return json_decode($response->getBody(), true);
  }
  throw new \RuntimeException('API request failed');
  

• Laravel HTTP Client Wrapper: Extend Laravel’s Http client to use Buzz for specific endpoints:

  $response = Http::withOptions(['handler' => $buzzHandler])->get('https://external-api.com');
  

3. Authentication

• Pattern: Add headers for auth (e.g., Bearer tokens):

  $request = new Request('GET', 'https://api.example.com/protected');
  $request->setHeader('Authorization', 'Bearer ' . $token);
  

• Laravel Auth Integration: Use middleware to inject auth headers:

  $request->setHeader('Authorization', 'Bearer ' . auth()->token());
  

4. Retry Logic

• Pattern: Implement retries for transient failures (e.g., 5xx, 429):

  $maxRetries = 3;
  for ($i = 0; $i < $maxRetries; $i++) {
      $response = $client->sendRequest('GET', 'https://api.example.com/data');
      if ($response->getStatusCode() < 500) break;
      sleep(2 ** $i); // Exponential backoff
  }
  

5. Streaming Responses

• Pattern: Stream large responses (e.g., file downloads):

  $response = $client->sendRequest('GET', 'https://example.com/large-file.zip');
  file_put_contents('large-file.zip', $response->getBody());
  

Integration Tips

1. Laravel Service Providers: Bind Buzz’s Browser to the container for dependency injection:

   $this->app->singleton(Browser::class, function () {
       return new Browser();
   });
   

2. Configurable Base URLs: Store API endpoints in config/services.php:

   'api' => [
       'base_url' => env('API_BASE_URL'),
       'timeout' => 30,
   ],
   

   Then use them in your service class:

   $response = $client->sendRequest('GET', config('services.api.base_url') . '/users');
   

3. Mocking for Tests: Use Buzz’s MockHandler to simulate responses:

   use Buzz\Message\Response;
   use Buzz\MockHandler;
   
   $mock = new MockHandler();
   $mock->setDefaultResponse(new Response(200, [], '{"test": true}'));
   
   $client = new Browser();
   $client->setHandler($mock);
   
   $response = $client->sendRequest('GET', 'https://fake-api.com');
   

4. Middleware for Requests: Create a middleware to modify requests (e.g., add headers):

   class AddHeadersMiddleware {
       public function __invoke(Request $request) {
           $request->setHeader('X-Custom-Header', 'value');
           return $request;
       }
   }
   

   Apply it before sending:

   $request = (new AddHeadersMiddleware())($request);
   $client->send($request);
   

Gotchas and Tips

Pitfalls

1. Connection Timeouts:

   • Buzz does not enforce timeouts by default. Set them explicitly:

     $client = new Browser();
     $client->setTimeout(10); // 10 seconds
     

   • Laravel Tip: Use Http::timeout() for Laravel’s HTTP client if wrapping Buzz.

2. Redirect Handling:

   • Buzz follows redirects by default. Disable with:

     $client->setFollowRedirects(false);
     

   • Debugging: Check Response::getEffectiveUrl() to see where a request redirected.

3. SSL/TLS Issues:

   • Buzz uses PHP’s stream_context_create for SSL. If you encounter issues:

     $context = stream_context_create([
         'ssl' => [
             'verify_peer' => false,
             'verify_peer_name' => false,
         ]
     ]);
     $client->setHandler(new \Buzz\Handler\CurlHandler($context));
     

   • Warning: Disable verification only for testing or trusted environments.

4. Memory Leaks with Large Responses:

   • Streaming responses (e.g., file downloads) avoids memory issues:

     $response = $client->sendRequest('GET', 'https://example.com/large-file');
     $stream = fopen('file.zip', 'w');
     fwrite($stream, $response->getBody());
     fclose($stream);
     

5. Case-Sensitive Headers:

   • Header names are case-insensitive in HTTP but may behave unexpectedly in some libraries. Stick to lowercase:

     $request->setHeader('content-type', 'application/json');
     

Debugging Tips

1. Log Requests/Responses:

   • Use a custom handler to log traffic:

     $handler = new class extends \Buzz\Handler\CurlHandler {
         public function send(Request $request) {
             \Log::debug('Request:', [
                 'url' => $request->getUrl(),
                 'method' => $request->getMethod(),
                 'headers' => $request->getHeaders(),
             ]);
             return parent::send($request);
         }
     };
     $client->setHandler($handler);
     

2. Inspect Raw Responses:

   • Dump the raw response body for debugging:

     \Log::debug('Raw Response:', $response->getBody());
     

3. Handle Malformed JSON:

   • Validate JSON responses before decoding:

     $body = $response->getBody();
     json_decode($body); // Throws exception if invalid
     

Extension Points

1. Custom Handlers:

   • Implement Buzz\Handler\HandlerInterface for custom logic (e.g., proxy support):

     class ProxyHandler implements HandlerInterface {
         public function send(Request $request) {
             // Add proxy logic here
             return new Response(200, [], 'Proxy response');
         }
     }
     $client->setHandler(new ProxyHandler());
     

2. Event Dispatching:

   • Trigger events before/after requests (e.g., logging, analytics):

     $client->on('request', function (Request $request) {
         \Log::info('Request sent', ['url' => $request->getUrl()]);
     });
     

3. Response Transformers:

   • Chain transformers to modify responses:

     $response = $client->sendRequest('GET', 'https://api.example.com/data');
     $data = (new JsonTransformer())->transform($response);
     

4. Retry Middleware:

   • Extend Buzz to support retries with exponential backoff: