Lumen Rate Limiting Laravel Package

Getting Started

• Install with composer require rogervila/lumen-rate-limiting:^2.0. Version 2.x targets Lumen 11; if you're still on Lumen 9/10, pin ^1.2 — the major bump is a dependency-constraint break, not an API redesign, so most 1.x usage examples still apply.
• Lumen does not auto-discover packages. Register the service provider explicitly in bootstrap/app.php:

  $app->register(Rogervila\LumenRateLimiting\RateLimitingServiceProvider::class);
  

• If the package ships a config file, Lumen also won't load it automatically. Copy it into config/ and add $app->configure('rate-limiting'); (or whatever the package names it) in bootstrap/app.php before the provider registration.
• Confirm a real cache store is configured. Rate limiting is counter-based, so CACHE_DRIVER=array works for tests but resets every request — production needs redis, memcached, database, or file with a shared volume.
• First use case worth wiring up: throttle a public auth or webhook endpoint. Attach the middleware to a route or group in routes/web.php and hit it in a loop with curl to confirm you get a 429 after N requests.

Implementation Patterns

• Route-group throttling is the natural fit in Lumen's terse routing style:

  $router->group(['middleware' => 'throttle:60,1'], function () use ($router) {
      $router->post('/login', 'AuthController@login');
  });
  

  Register the short alias in bootstrap/app.php via $app->routeMiddleware([...]) if the package exposes an alias; otherwise pass the FQCN.
• Key by identity, not just IP. Ordering matters: if throttling sits before your auth middleware, every request keys on IP (bad behind NAT/offices); placed after auth, you can key on the authenticated user. Pick deliberately per route and document it.
• Tiered limits per route class. Cheap read endpoints get generous windows; write/auth/reset-password endpoints get tight ones. Keep the numbers in config rather than inline middleware strings so ops can tune without a deploy.
• Custom 429 responses. Most of these packages let you swap the response (via a bound handler or by extending the middleware). Return Retry-After plus a JSON body matching your API's error envelope — clients and HTTP caches both use that header.
• Test with a frozen clock. Use Cache::flush() in setUp() and Laravel's time-travel helpers to assert the window actually decays, rather than just asserting the 429. A limiter that never resets is the most common silent bug.
• Compose with idempotency. For webhooks/queues, pair the limiter with your own idempotency key so retried deliveries don't burn the caller's quota twice.

Gotchas and Tips

• The 2.0.0 change is a platform bump. Treat the upgrade as "does my Lumen version satisfy the new illuminate/* constraints?" Run composer why-not rogervila/lumen-rate-limiting 2.0.0 before assuming the code needs changes. Expect to also bump laravel/lumen-framework to ^11.0.
• Silent no-op with the array cache. In APP_ENV=local with CACHE_DRIVER=array, every request starts with an empty counter — limits never trigger and you'll wrongly conclude the middleware isn't registered. Test against Redis or at least file.
• Multi-server setups need a shared store. File cache on ephemeral containers gives each replica its own counter, effectively multiplying your limit by the pod count.
• IP resolution behind a load balancer. If TrustProxies-equivalent middleware isn't configured, keys collapse to the proxy IP and one noisy client locks out everyone. Lumen requires this to be set up manually.
• Middleware order is invisible in Lumen. There's no route:list showing the resolved stack. Debug by dumping inside the middleware or temporarily logging the computed cache key — that key tells you instantly whether you're keying by IP, user, or route.
• Config not loaded = defaults, not errors. Missing $app->configure(...) silently falls back to package defaults, so limits appear to ignore your config file. Verify with config('...') in tinker/a scratch route.
• Extension points to reach for first: subclass the middleware to override the key resolver and the response factory; bind your own limiter/store implementation in the container if you need per-tenant quotas. Prefer this over forking.
• Flushing limits during an incident is just a cache-key delete on the shared store — know the key prefix ahead of time (artisan cache:clear on Redis nukes everything else too).
• Pin the major version in composer.json and note the Lumen 11 requirement in your upgrade notes; this package moves in lockstep with Lumen majors and won't backport.