Laravel Sliding Window Limiter Laravel Package

Product Decisions This Supports

• Defining what "per hour" actually means in your API contract. "1,000 requests/hour" is underspecified until you choose a window model. A fixed calendar window lets a client burn the full quota at 10:59 and again at 11:00 — roughly 2× the intended rate — while a sliding window enforces the quota the customer thinks they bought. This package is a concrete reference for the sliding model, and that single choice propagates into public docs, SDK retry logic, sales collateral, and the volume of "why am I being throttled?" tickets.
• Tier and packaging design. Burst tolerance is a product feature, not an implementation detail. Strict pacing produces a predictable, premium-feeling tier; loose windows produce spiky behavior and intermittent 429s at the top of the hour. Deciding which tiers get which behavior is a pricing decision that this package's algorithm makes tangible.
• Protecting outbound integrations. The realistic failure mode with payments, SMS, identity, and customer webhook endpoints is not sustained overload — it is a doubled burst at a window boundary tripping a vendor's own rolling-window limit. Matching our enforcement semantics to the vendor's is a reliability and vendor-relationship decision.
• Multi-tenant fairness. Per-tenant keying contains noisy neighbors. One account exhausting a shared budget is a churn and CSAT problem that shows up in support queues long before it shows up in error budgets.
• Client-facing correctness as a contract. Accurate Retry-After and X-RateLimit-* values, honest 429 bodies, and documented reset semantics. A limiter with fuzzy reset behavior manufactures retry storms — and customers will build SDKs against whatever we publish.
• Failure-mode policy with a named owner. Fail-open vs. fail-closed when Redis is unavailable decides whether a cache blip is a latency incident or a full outage. This is a product risk acceptance, not an SRE default.
• Build vs. buy vs. borrow. This package lands in borrow: read and reimplement the approach under MIT attribution rather than take the dependency. Settling that early avoids a forced migration later.
• Roadmap: app-level middleware vs. centralized traffic policy. Whether throttling stays a Laravel middleware concern or graduates into a shared gateway layer as services, regions, and tenants multiply. This package only ever addresses the first world.

When to Consider This Package

Consider the approach when:

• Quotas are contractual or customer-visible as "any rolling 60 minutes," or an upstream vendor enforces rolling windows and you want matching semantics.
• Traffic is bursty and boundary doubling has already caused — or plausibly causes — incidents against downstream dependencies.
• Abuse and spike protection matter more than sub-millisecond limiter overhead.
• You want a compact, readable reference for a Redis sorted-set sliding-window design to inform an in-house build.

Do not adopt this as a dependency. It is archived, last released September 2019, has 42 stars and zero known dependents, and predates Laravel 8/9/10/11 and PHP 8.x. There is no maintainer to ship compatibility fixes or respond to a limiter-bypass report. A rate limiter sits on the hot path of every request and functions as a security and cost control — that is not a component to source from an unmaintained repository. The MIT license permits copying the logic with attribution; that is the sane path.

Look elsewhere — or build — when:

• Redis memory matters. A precise sliding-window log stores roughly one entry per request (O(limit) per key). At high limits or high key cardinality (per-tenant-per-route-per-IP) that is real cost and a hot-shard risk; a sliding-window counter approximation or token bucket is far cheaper.
• You need burst allowance rather than strict pacing. Token bucket is the better fit; leaky bucket for smoothing.
• Enforcement must be shared across services or regions. That is a gateway concern (Envoy, Kong, Cloudflare, or a dedicated policy service), not per-app middleware.
• Redis is not already a tier-0, well-operated dependency. Introducing it solely for limiting turns a Redis blip into an availability incident.
• Laravel's native Redis::throttle() already clears the bar. It is sorted-set based and effectively sliding. Evaluate it first; the delta may not justify any new code.

Adoption criteria to resolve before writing code: target Laravel/PHP/Redis versions; the purpose (abuse prevention vs. cost control vs. SLA enforcement vs. tenant fairness); Redis topology (single, Sentinel, Cluster, managed) and whether the Lua operations stay within one hash slot; header requirements; and whether the team can own a fork. If any of these is unresolved, the correct answer is a spike, not a dependency.

How to Pitch It (Stakeholders)

For executives. Rate limiting is simultaneously a pricing surface, a fairness mechanism, and a trust signal — it determines whether customers experience their purchased quota as predictable or arbitrary. Sliding-window limiting is the more defensible model, and this package is a useful reference implementation of it. We should not take it as a dependency: archived since 2019, 42 stars, zero dependents, no maintainer, no security response path, and almost certainly incompatible with our current Laravel and PHP versions. Recommendation: borrow the algorithm, not the code. Estimated effort is small — a time-boxed spike plus a modest middleware with concurrency and Redis-outage tests — and it keeps an unmaintained component off the critical path of every request. Two decisions are needed from product: (1) confirm rolling-window semantics for all published quotas and update the API contract and docs accordingly; (2) choose fail-open or fail-closed behavior when Redis is unavailable, and accept the consequences of that choice explicitly.

For engineering. Treat the repository as a design document, not a dependency; MIT permits reimplementation with attribution. Price in three things: memory — a per-request sorted-set log is O(limit) per key, so define key granularity, TTLs, and ZREMRANGEBYSCORE eviction deliberately and watch for hot shards on high-cardinality keys; atomicity — check-and-record must be a single Lua script, and under Redis Cluster the keys must be hash-tagged into one slot; availability and latency — the limiter is now on every request path, so add a documented Redis failure policy, p50/p99 limiter latency metrics, and a 429-rate-by-tenant dashboard before broad rollout. Recommended sequence: a time-boxed spike comparing this algorithm against Laravel's built-in Redis::throttle() and a token-bucket alternative; then a small internal middleware behind a feature flag, wrapped behind an internal SlidingWindowLimiter interface so the implementation is swappable; shadow-mode it on a low-traffic route and diff decisions against current behavior before enforcing. Document the external contract — window type, key granularity, limit values, headers, reset behavior, failure mode — in the public API docs, because that contract is what customers and their SDKs will integrate against.

For a legacy carve-out. The only scenario where installing the artifact is defensible is a Laravel 5.8/6.x application on PHP 7.x with a bounded remaining lifespan and an existing Redis dependency, where a fork is cheaper than a rewrite. Even then, name an internal maintainer and a release process; ownership is what actually gates this decision.