- How do I install and set up aporat/laravel-rate-limiter in a Laravel app?
- Install it with composer require aporat/laravel-rate-limiter, then publish the package config file and register the rate.limiter middleware alias so it can be attached to routes and route groups. Laravel package auto-discovery registers the service provider, so no manual provider entry is normally needed. After that, limits can be declared inline in routes or programmatically through the RateLimit facade.
- Which Laravel and PHP versions does aporat/laravel-rate-limiter support?
- Version 6 modernizes the internals for current Laravel lines — configuration is read through Illuminate\Contracts\Config\Repository and Redis goes through Laravel's Redis manager — and it targets PHP 8.3 and above. Lumen support was dropped in v6, so Lumen applications need to stay on v5 or migrate. Always confirm the exact supported Laravel versions against the CI matrix in the repository before committing to an upgrade.
- How do I configure different limits per second, minute and hour on a route?
- Use the validated middleware DSL directly in the route definition, for example rate.limiter:second=,minute=60,hourly=1000,key=ip+route,name=api. Each declared window is evaluated atomically in a single Redis Lua script per request, so a request is either allowed or refused without race conditions. Windows you leave out are simply not enforced, which keeps the policy declarative and readable.
- How do I rate limit by user ID, IP or a custom key?
- Build a limiter with RateLimit::with() and key it by user ID, IP, route or a custom segment, then call attempt() to receive a LimitResult. Segment escaping means withUserId('a:b') no longer collides with withUserId('a')->withName('b'), and requests with a missing IP no longer share one bucket. That keeps counters distinct per subject instead of silently merging traffic.
- Is aporat/laravel-rate-limiter safe to use with Laravel Octane or RoadRunner?
- Yes. The facade returns an immutable builder and the bound singleton holds no request state, so limits cannot leak between requests in long-running workers. All counter state lives in Redis rather than process memory, which is exactly what Octane and RoadRunner need.
- Which Redis connection does it use, and does it support clusters, TLS and REDIS_URL?
- The package no longer maintains a parallel Redis config; it delegates to Laravel's Redis manager with named connections, so TLS, cluster and REDIS_URL settings come from your existing config/database.php. Whether you use phpredis or predis is therefore your existing Laravel configuration choice, not a package-level setting. Note that all windows for one subject share a cluster hash tag, so a single abusive client maps to a single shard by design.
- What happens to rate-limited routes if Redis goes down?
- Failure behavior is an explicit decision via on_redis_failure: open lets traffic through, closed returns 503, and failure_backoff_seconds controls how quickly it retries. Because Redis sits on the synchronous critical path of every limited endpoint, choose per route class — closed for login and write endpoints, open for read-only endpoints — rather than one global default.
- Which rate limit headers does the package return?
- Responses expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Those names changed in v6, and old header names do not error — they simply disappear, so client SDKs, mobile backoff logic, gateway rules and contract tests that parse them degrade to naive retry. The withRateLimitHeaders() helper was also removed, so re-check header emission if you relied on toggling it or emitting headers in parallel.
- What are the breaking changes when upgrading from v5 to v6?
- v6 removes withRateLimitHeaders(), setRequestTag(), getRequestTag(), checkIpAddress(), the redis.* settings and Lumen support, and renames the rate limit headers. It also fixes a security issue: v5's default whitelist included 10.0.0.0/8, so behind a trust-all proxy any client presenting a private address could be exempt from limiting entirely. On top of that, refused requests no longer increment the other windows and key segment escaping changed, so expect visible counter churn on cutover.
- How do I test rate-limited endpoints in my test suite?
- Use the programmatic surface — RateLimit::with(), PendingLimit::attempt(), LimitResult, RateLimiter::attempt() and blockedFor() — to assert remaining counts and reset windows in feature tests. Assert on the RateLimitExceeded and IpBlocked events to verify 429 responses and blocking flows. Because the builder is immutable and the singleton is stateless, you do not need to reset facade state between tests, but point the package at a dedicated cache or Redis connection.