Throttle Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-http/throttle-plugin
   

   Ensure symfony/rate-limiter is also installed (dependency).

2. Basic Usage

   use Http\Client\Common\Plugin\ThrottlePlugin;
   use Symfony\Component\RateLimiter\RateLimiterFactory;
   
   // Create a rate limiter (e.g., 10 requests per minute)
   $rateLimiter = RateLimiterFactory::create(['10/minute']);
   
   // Initialize the plugin
   $throttlePlugin = new ThrottlePlugin($rateLimiter);
   
   // Add to your HTTP client
   $client = new \Http\Client\Common\PluginClient();
   $client->addPlugin($throttlePlugin);
   

3. First Use Case Throttle API requests to avoid hitting rate limits:

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

Implementation Patterns

Workflow Integration

1. Centralized Throttling

   • Configure throttling at the client level (e.g., in a service container or HTTP client factory).
   • Example: Laravel service provider binding:

     $this->app->singleton(\Http\Client\Common\PluginClient::class, function ($app) {
         $client = new \Http\Client\Common\PluginClient();
         $client->addPlugin(new ThrottlePlugin(RateLimiterFactory::create(['10/minute'])));
         return $client;
     });
     

2. Dynamic Rate Limits

   • Use environment variables or config files to define limits per API:

     $limits = config('http.throttle');
     $rateLimiter = RateLimiterFactory::create($limits['api.example.com']);
     

3. Retry Logic

   • Combine with Http\Client\Common\Plugin\RetryPlugin to retry throttled requests:

     $client->addPlugin(new RetryPlugin());
     $client->addPlugin($throttlePlugin);
     

Common Patterns

• Per-Endpoint Throttling: Attach different rate limiters to specific requests via middleware or decorators.
• Burst Handling: Use Symfony\Component\RateLimiter\Storage\MemoryStorage for in-memory throttling (e.g., for testing).
• Logging: Log throttled requests for monitoring:

  $throttlePlugin->onThrottled(function (Request $request, \DateInterval $wait) {
      \Log::warning("Throttled: {$request->getUri()}. Retry after {$wait->s} seconds.");
  });
  

Gotchas and Tips

Pitfalls

1. Storage Backend

   • Default MemoryStorage is not persistent across requests. For distributed systems, use:

     use Symfony\Component\RateLimiter\Storage\RedisStorage;
     $storage = new RedisStorage(new \Redis());
     $rateLimiter = RateLimiterFactory::create(['10/minute'], $storage);
     

2. Concurrency Issues

   • Throttling is not thread-safe by default. Ensure single-threaded execution or use a shared storage backend.

3. Plugin Order

   • Place ThrottlePlugin before other plugins that might modify requests (e.g., RetryPlugin).

Debugging Tips

• Check Rate Limits: Use RateLimiterInterface::consume() to manually test limits:

  $rateLimiter->consume(1)->wait(); // Simulate a request
  

• Log Wait Times: Override onThrottled to log delays:

  $throttlePlugin->onThrottled(function ($request, $wait) {
      \Log::debug("Wait time: {$wait->s} seconds for {$request->getUri()}");
  });
  

Extension Points

1. Custom Rate Strategies
   • Implement Symfony\Component\RateLimiter\RateLimiterInterface for custom logic (e.g., token buckets).
2. Event Hooks
   • Extend ThrottlePlugin to trigger events before/after throttling:

     $throttlePlugin->onBeforeThrottle(function ($request) {
         // Pre-throttle logic
     });
     

3. Middleware Integration
   • Wrap Laravel HTTP clients to enforce throttling at the framework level:

     $client->addPlugin(new ThrottlePlugin(
         RateLimiterFactory::create(['5/second'])
     ));