Buzz Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require kriswallsmith/buzz nyholm/psr7
   

   • Buzz requires a PSR-17 factory (e.g., nyholm/psr7).

2. First Request:

   use Buzz\Browser;
   use Buzz\Client\Curl;
   use Nyholm\Psr7\Factory\Psr17Factory;
   
   $factory = new Psr17Factory();
   $client = new Curl($factory);
   $browser = new Browser($client, $factory);
   
   $response = $browser->get('https://example.com');
   echo $response->getStatusCode(); // 200
   

3. Key Classes:

   • Browser: High-level wrapper for HTTP requests (supports middleware).
   • Curl, FileGetContents, MultiCurl: Low-level clients (choose based on needs).
   • Psr17Factory: Required for PSR-7 request/response creation.

Implementation Patterns

1. Browser for Common Use Cases

• Middleware Chain:

  $browser->addMiddleware(new \Buzz\Middleware\LoggerMiddleware());
  $browser->addMiddleware(new \Buzz\Middleware\BasicAuthMiddleware('user', 'pass'));
  

• Form Submission:

  $response = $browser->submitForm(
      'https://example.com/login',
      ['email' => 'user@example.com', 'password' => 'secret']
  );
  

• Custom Headers:

  $browser->setHeader('X-Custom-Header', 'value');
  

2. Low-Level Clients for Control

• Curl for Advanced Options:

  $client = new Curl($factory, ['timeout' => 10, 'verify_peer' => false]);
  $response = $client->sendRequest($request, ['expose_curl_info' => true]);
  

• MultiCurl for Batch Requests:

  $multiClient = new MultiCurl($factory);
  $multiClient->sendAsyncRequest($request1);
  $multiClient->sendAsyncRequest($request2);
  $responses = $multiClient->proceed(); // Array of responses
  

• HTTP/2 Server Push:

  $client = new MultiCurl($factory);
  $response = $client->sendRequest($request, ['http_version' => '2.0']);
  

3. Integration with Laravel

• Service Provider:

  // app/Providers/BuzzServiceProvider.php
  public function register()
  {
      $this->app->singleton('buzz.browser', function () {
          $factory = new Psr17Factory();
          $client = new Curl($factory);
          return new Browser($client, $factory);
      });
  }
  

• Facade (Optional):

  // app/Facades/Buzz.php
  public static function get($url) {
      return app('buzz.browser')->get($url);
  }
  

4. Error Handling

• Middleware for Retries:

  $browser->addMiddleware(new class implements \Buzz\Middleware {
      public function __invoke($request, callable $next) {
          try {
              return $next($request);
          } catch (\Buzz\Exception\RequestException $e) {
              return $next($request); // Retry
          }
      }
  });
  

• Custom Exceptions:

  try {
      $response = $browser->get('https://invalid.url');
  } catch (\Buzz\Exception\RequestException $e) {
      Log::error('Request failed:', ['error' => $e->getMessage()]);
  }
  

Gotchas and Tips

Pitfalls

1. Timeout Default:
   • Default timeout is 0 (no limit). Explicitly set:

     $client = new Curl($factory, ['timeout' => 30]);
     

2. Redirects:
   • Disabled by default (unlike Guzzle). Enable with:

     $browser->setOption('max_redirects', 5);
     

3. HTTP/2 Requirements:
   • Requires PHP ≥ 7.4 + cURL ≥ 7.61.1 + libnghttp2.
   • Test locally with Docker (see README).
4. Cookie Handling:
   • Use CookieMiddleware for persistent cookies:

     $browser->addMiddleware(new \Buzz\Middleware\Cookie\CookieMiddleware());
     

5. MultiCurl Async Behavior:
   • sendAsyncRequest() is non-blocking. Use proceed() to fetch results.
   • Exceptions in async requests are silently ignored by default. Use callbacks for error handling:

     $multiClient->sendAsyncRequest($request, ['callback' => function ($response) {
         if ($response->getStatusCode() >= 400) {
             throw new \RuntimeException('Failed');
         }
     }]);
     

Debugging Tips

1. Expose cURL Info:

   $response = $client->sendRequest($request, ['expose_curl_info' => true]);
   $info = $response->getAttribute('curl_info');
   

2. Logger Middleware:

   $browser->addMiddleware(new \Buzz\Middleware\LoggerMiddleware(
       new \Monolog\Logger('buzz')
   ));
   

3. Validate Responses:
   • Check status codes explicitly:

     if ($response->getStatusCode() !== 200) {
         throw new \RuntimeException('Unexpected status: ' . $response->getStatusCode());
     }
     

Extension Points

1. Custom Middleware:
   • Implement \Buzz\Middleware for request/response transformation:

     $browser->addMiddleware(new class implements \Buzz\Middleware {
         public function __invoke($request, callable $next) {
             $request = $request->withHeader('X-My-Header', 'value');
             return $next($request);
         }
     });
     

2. Response Factories:
   • Extend Psr17Factory to customize request/response creation.
3. Client Options:
   • Configure defaults via AbstractClient::configureOptions():

     Curl::configureOptions(function (\Symfony\Component\OptionsResolver\OptionsResolver $resolver) {
         $resolver->setDefaults(['timeout' => 10]);
     });
     

Performance Notes

• FileGetContents: Fastest for simple requests (no redirects/cookies).
• Curl: Best for complex requests (auth, timeouts, headers).
• MultiCurl: Optimize for batch requests (e.g., scraping):

  $start = microtime(true);
  $multiClient->sendAsyncRequest($request1);
  $multiClient->sendAsyncRequest($request2);
  $responses = $multiClient->proceed();
  $duration = microtime(true) - $start;
  

Laravel-Specific Quirks

1. Queue Jobs:
   • Use MultiCurl for parallel HTTP jobs in queues:

     $multiClient = new MultiCurl($factory);
     foreach ($urls as $url) {
         $multiClient->sendAsyncRequest($browser->createRequest('GET', $url));
     }
     $results = $multiClient->proceed();
     

2. Caching:
   • Combine with Laravel’s cache:

     $cacheKey = 'buzz:response:' . md5($url);
     $response = Cache::get($cacheKey);
     if (!$response) {
         $response = $browser->get($url);
         Cache::put($cacheKey, $response, now()->addHours(1));
     }