Guzzle Rate Limiter Middleware Laravel Package

Technical Evaluation

Architecture fit. This is an HTTP-client-level concern, not a framework concern. The package is a single Guzzle middleware plus a two-method Store interface — there is no service provider, no config file, no facade, no publishable assets. That is a good fit for a Laravel codebase precisely because it makes no architectural demands: it composes into whatever HandlerStack you already build, and the integration seam is a singleton binding in a service provider. The one architectural commitment it forces is that outbound calls to a rate-limited provider must go through one shared, configured Guzzle client. If the codebase calls providers ad hoc via new Client(), Http::get() without a handler, or a mix of Guzzle and cURL, the limiter is decorative. Scoping this package therefore means scoping an outbound-client standardization effort — modest, but it is real work and should be planned as such.

Integration feasibility. High. The public API is two static factories (perSecond, perMinute) and one interface to implement. A single engineer can wire a working client in under an hour; a production-grade version with a shared store, logging deferrer, and retry interplay is one to two days. The genuine design work is not the package — it is the Store implementation, which the package deliberately leaves to us. The README's example store (plain array_merge, no pruning, no TTL) is a sketch and must not be merged; it leaks unbounded cache entries and creates a read-modify-write race.

Technical risk. Ranked by what would actually hurt:

Key questions to resolve before committing:

1. What are the actual provider quotas — per second or per minute, and is there burst allowance? The package supports exactly two units, so a quota expressed as "1000/day" needs a different mechanism.
2. How many concurrent processes (queue workers, scheduled commands, web requests) will share this quota? That single number determines whether we are shipping an in-memory toy or a distributed store.
3. Do we have Redis (or another atomic shared store) in every environment that will run this? If not, the distributed-store requirement becomes an infrastructure dependency, not a code task.
4. Where will the sleeps land — background workers only, or user-facing request paths? If the latter, is the added latency an accepted product trade-off?
5. Is there an existing outbound-client abstraction to hang this on, or does adopting this package trigger a client-standardization effort?
6. What is the observability expectation — do we need pacing metrics and alerts on first adoption, or can that follow?
7. Is the retry semantics decision (retries count against budget) acceptable to the provider relationship owner?

Integration Approach

Stack fit. Laravel + Guzzle is the native environment: composer require spatie/guzzle-rate-limiter-middleware with ^2.2 pinned, PHP 8.3+, Guzzle 6.3/7/8. It also works through the Http facade, since options are forwarded to the underlying client — that path is viable but easier to get wrong, because the handler stack must be a singleton for the store to survive across calls in a worker. Recommendation: bind one configured client per external API as a container singleton, expose it as a small typed wrapper class, and make that wrapper the only sanctioned entry point. Tests then swap it through the container. That is the seam; everything else is an implementation detail.

Migration path. Do not attempt a codebase-wide sweep. Sequence by exposure:

1. Inventory outbound calls to the target provider — count call sites, identify which use raw Client, which use Http, which bypass both. This is the real cost estimate and should precede any packaging decision.
2. Pilot on one provider in one background worker. Choose the integration with a documented quota and no user-facing latency budget. Ship the configured client, cache-backed store, and logging deferrer together — shipping the client without the shared store is the classic mistake.
3. Instrument before widening. The Deferrer is injectable in v2; wrap SleepDeferrer, log every block with duration and provider, and emit a counter. You want the baseline stall profile before it affects anything a customer notices.
4. Migrate remaining call sites for that provider onto the singleton, deleting duplicated stack construction. Then repeat provider by provider.
5. Only then consider user-facing request paths, with explicit latency acceptance from the product owner.

If an existing ad hoc pattern is being replaced (hand-rolled usleep, hardcoded retry-with-delay, or nothing at all), the package is a net simplification — it consolidates behaviour that is currently duplicated per call site into one configured client. That consolidation is the primary deliverable; rate limiting is the vehicle.

Compatibility. Two hard gates: PHP ≥ 8.3 across every service and CI image, and ^2.2 pinned for Guzzle 8 environments. Verify the Guzzle major in composer.lock before rollout — a version resolution surprise here surfaces as a type error at the handler, not as a clean failure. Beyond that, the package has no framework coupling, so Laravel and PHP upgrades are unaffected, and the two-method Store interface means our store implementation is portable if we ever swap the limiter out.

Sequencing dependency to call out explicitly: stack ordering. The rate limiter must sit inside the retry middleware so retries are counted against the budget. Get this wrong and a 429 storm drains a budget that was never charged for the attempts. Worth a test that asserts the ordering rather than relying on reviewer attention.

Operational Impact

Maintenance. Low, and bounded. The package is small, single-purpose, MIT-licensed, actively released (PHP 8.4 and Guzzle 8 support both landed as versioned releases), and its public API has been stable since v2's Store::push($timestamp, $limit) signature change. It will not generate a backlog. The maintenance surface we inherit is the opposite of what the package ships: we own the Store implementation and the stack-composition wiring, and that is the code that will need care.

Support. Vendor support is community-grade — GitHub issues, Spatie's security contact for vulnerabilities. There is no SLA, no commercial backing, and the codebase is small enough to vendor or fork if abandoned, which materially de-risks the dependency. Internally, support burden concentrates on a single owner-adjacent question: "why is this worker slow?" Establish the logging deferrer up front and that question answers itself. Without it, support cost is entirely diagnostic guesswork.

Scaling. Scales along three axes that must each be addressed:

• Process count — the shared store is mandatory past one worker. This is the single most important scaling decision and it fails open if skipped.
• Throughput — one shared-store round trip per outbound request. At meaningful call volume that is a real Redis load and a real latency addition; it is acceptable for partner APIs called tens of times per minute, less so for high-fanout internal calls. Scope accordingly.
• Store growth — cap the stored timestamp array using the $limit value handed to push(), and set a TTL. Unbounded growth here is a slow-motion incident, not a bug report.

Horizontal scaling of the API tier does not change any of this, provided the store is externalized. Vertical scaling does not help — more concurrency against a shared quota just increases contention on the store.

Failure modes — enumerate these in the runbook, because most are silent:

1. In-memory fallback in production — limiter effectively disabled per process; manifests as provider 429s or a warning from the vendor, never as an application error.
2. Long blocking sleeps — worker exceeds its timeout or a job's SLA; shows up as unexplained latency, not as a rate-limit event.
3. Shared store unavailable — behaviour depends entirely on our implementation. Decide now whether it fails closed (block/stall) or open (no limiting). Fail-closed during a Redis blip is its own outage.
4. Store race — non-atomic read-modify-write over-admits; presents as intermittent 429s at correct nominal limits.
5. Clock skew across workers — timestamps diverge, pacing becomes erratic; the reason backoff must remain as a safety net.
6. Retry amplification — 429s plus retries consume budget fast; without correct stack ordering, the limiter under-counts and the problem compounds.

Pacing and backoff are complementary, not redundant. Budget for both.

Ramp-up. Roughly two days of engineering for one person, spread as: half a day to install, pin, and audit src/; half a day to build and test an atomic cache-backed store plus a logging deferrer; half a day on stack ordering and retry interaction with a covering test; half a day to wire the singleton and migrate the pilot provider's call sites. Add a day if client standardization is in scope. No new infrastructure is required beyond Redis, which is almost certainly already present. Total cost of ownership is dominated by the store we write, not by the package — which is the right way to frame the decision: this is a low-cost, low-risk, narrow-scope adoption that pays off only if the shared-store and observability work is committed alongside it. Adopting the middleware without those two pieces is worse than nothing, because it produces false confidence that a quota is being respected.