Buzz React Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require clue/buzz-react:^2.9
   

   Ensure your project uses ReactPHP (v1.0+) as the event loop.

2. Basic Request (Updated API)

   use Buzz\Browser;
   use React\EventLoop\Factory;
   
   $loop = Factory::create();
   $browser = new Browser($loop);
   
   $promise = $browser->request('GET', 'https://api.example.com/data');
   $promise->then(
       function ($response) {
           echo $response->getBody();
       },
       function ($error) {
           echo "Error: " . $error->getMessage();
       }
   );
   
   $loop->run();
   

3. First Use Case (Streaming Requests) Fetch and stream large responses efficiently:

   $browser = (new Browser($loop))->withResponseBuffer(50 * 1024 * 1024); // 50MB buffer
   $promise = $browser->requestStreaming('GET', 'https://api.example.com/large-file');
   
   $promise->then(function ($response) {
       $stream = $response->getBody();
       while (!$stream->isEof()) {
           echo $stream->read();
       }
   });
   

Implementation Patterns

Async Workflows (Updated API)

• Chaining Requests with New Methods Use request() and requestStreaming() for clarity:

  $browser->request('GET', 'https://api.example.com/token')
      ->then(function ($response) {
          $token = json_decode($response->getBody(), true)['token'];
          return $browser->request('GET', 'https://api.example.com/protected', [
              'headers' => ['Authorization' => "Bearer $token"]
          ]);
      });
  

• Retry Logic with Buffer Control Combine retry logic with response buffering:

  use React\Promise\Timer\TimeoutException;
  
  $retry = \React\Promise\retry(
      3,
      function ($attempt) use ($browser) {
          return $browser->withResponseBuffer(10 * 1024 * 1024) // 10MB per retry
              ->request('GET', 'https://api.example.com')
              ->otherwise(function ($error) {
                  throw new TimeoutException("Retry $attempt failed", 0, $error);
              });
      }
  );
  

Integration with Laravel (Updated API)

• Service Provider (New Methods) Bind Browser with updated configuration:

  public function register()
  {
      $this->app->singleton(Browser::class, function ($app) {
          $loop = Factory::create();
          $browser = new Browser($loop);
          return $browser
              ->withTimeout(10)
              ->withFollowRedirects(false)
              ->withResponseBuffer(16 * 1024 * 1024); // Default 16MB
      });
  }
  

• Queue Workers with Streaming Process large files asynchronously:

  $loop = Factory::create();
  $browser = (new Browser($loop))->withResponseBuffer(100 * 1024 * 1024); // 100MB
  
  $loop->addPeriodicTimer(1, function () use ($browser) {
      $browser->requestStreaming('GET', 'https://api.example.com/queue')->then(
          function ($response) {
              // Stream response to disk/file
          }
      );
  });
  

• Middleware for Options Use dedicated methods instead of withOptions():

  $browser = (new Browser($loop))
      ->withTimeout(5)
      ->withFollowRedirects(true)
      ->withRejectErrorResponse(false);
  
  $browser->setMiddleware(function ($request, $next) {
      $request = $request->withHeader('X-Custom-Header', 'value');
      return $next($request);
  });
  

New: Base URL Management

• Dynamic Base URLs

  $browser = (new Browser($loop))->withBase('https://api.example.com/v1');
  
  // Resets base URL
  $browser->withBase(null)->request('GET', 'https://new-api.example.com');
  

Gotchas and Tips

Common Pitfalls (Updated)

1. Deprecated APIs

   • Issue: send(), submit(), withOptions(), and UriInterface are deprecated.
   • Fix: Replace with:

     // Old: $browser->send(new Request('GET', $url));
     // New: $browser->request('GET', $url);
     
     // Old: $browser->submit($url, $data);
     // New: $browser->post($url, ['headers'], http_build_query($data));
     

2. Buffer Management

   • Issue: Default 16MB buffer may cause memory issues for large responses.
   • Fix: Explicitly set buffer size:

     $browser->withResponseBuffer(50 * 1024 * 1024); // 50MB
     

3. Streaming vs. Buffering

   • Issue: Mixing request() and requestStreaming() may lead to unexpected behavior.
   • Fix: Use requestStreaming() for large payloads and request() for small responses.

Debugging Tips

• Enable ReactPHP Debug Mode

  $loop->addPeriodicTimer(0.1, function () {
      echo "Loop running...\n";
  });
  

• Log Deprecation Warnings Enable PHP error reporting to catch deprecated API usage:

  error_reporting(E_ALL | E_STRICT);
  

Extension Points (New Features)

1. Custom Response Buffers Override buffer logic for specialized use cases:

   $browser = new Browser($loop);
   $browser->setMiddleware(function ($request, $next) {
       return $next($request)->then(function ($response) {
           $body = $response->getBody();
           if ($body->getSize() > 100 * 1024 * 1024) { // 100MB
               return $browser->requestStreaming($request->getMethod(), $request->getUri());
           }
           return $response;
       });
   });
   

2. Rate Limiting with Streaming Throttle streaming requests:

   $lastRequest = 0;
   $browser->requestStreaming('GET', 'https://api.example.com/stream')->then(
       function () use (&$lastRequest) {
           $lastRequest = time();
       }
   );
   
   $loop->addPeriodicTimer(1, function () use ($browser, &$lastRequest) {
       if (time() - $lastRequest > 1) { // 1 request per second
           $browser->requestStreaming('GET', 'https://api.example.com/stream');
       }
   });
   

3. Documentation Overhaul

   • Tip: Use the updated docs for:
     • Concurrency patterns.
     • Streaming best practices.
     • Method reference (e.g., withTimeout(), withFollowRedirects()).