Rate Limit Plugin Laravel Package

Technical Evaluation

Architecture fit saloonphp/rate-limit-plugin is an add-on to Saloon, a framework-agnostic PHP HTTP client. It is not a Laravel package in the strict sense — it has no service provider, config file, or facade — but it is directly relevant to any Laravel service that makes outbound calls to third-party APIs with quotas (payments, messaging, carrier/booking APIs, SaaS rate-limited endpoints). It sits in the same layer as Saloon itself: behind an application-owned integration/service class, not in controllers. That is a healthy architecture fit, because rate limiting is a cross-cutting concern of the outbound-connector layer and this package keeps it there rather than leaking quota logic into domain code.

Integration feasibility Feasible and small: a Composer require plus plugin registration on each connector (or a trait on the connector base class). No infrastructure prerequisite beyond a cache store the package can reach. Expect hours, not weeks, for a first connector — the real effort is per-connector configuration of limits, which is business-knowledge work (what each vendor's actual quota is), not engineering work.

Technical risk This release is a patch that fixes a correctness defect: cached responses were being counted against the rate limit. Two consequences matter to a TPM.

1. Silent throughput change. Rate-limit accounting changed at patch level. Any connector tuned while the bug was live may have been compensating for wrong behaviour (either over-throttling by being over-counted, or — the more likely user-visible symptom — 429s from upstream because cached-then-replayed responses consumed quota invisibly or were miscounted). Expect small, hard-to-attribute differences in call volume and 429 rates after upgrading. This is low blast radius but non-obvious, and it will not appear in any diff a reviewer reads.
2. Plugin composition is the fragile seam. The bug only exists when a caching plugin and the rate-limit plugin are used together on the same connector — i.e. the failure mode is in Saloon's plugin pipeline ordering/interaction, not in either package alone. That is a category of risk to expect repeatedly, and it argues for integration tests on connectors that stack plugins.

Key questions

• Which of our connectors stack caching with rate limiting, and in what registration order?
• Where does the counter live — shared Redis or per-node? (Determines whether limits are real under horizontal scaling.)
• Do we have a test or metric that would have caught this bug class in our own code?
• Is the package's supported Saloon core major version aligned with what we run?
• Who owns watching this changelog, given patches can change observable behaviour?

Integration Approach

Stack fit Composer package, PHP 8.x, no Laravel coupling. Works with any Laravel version whose PHP constraint matches; the only Laravel-specific decision is which cache store backs the limit counter. Redis (or another shared store) is the correct choice for any multi-instance deployment; array/file caches make limits per-process and are only acceptable in local dev.

Migration path

• New adoption: constrain to ^2.5.3 so the fix is included from day one. No reason to accept earlier 2.5.x.
• Existing 2.5.x: routine composer update, no code change expected. Treat it as a behaviour change for review purposes regardless — re-run connector integration tests and compare 429 rates before/after.
• Pre-2.5: read the intervening changelog for breaking changes; do not jump majors blind.

Compatibility Verify three constraints before merging: package's required Saloon core version, PHP version floor, and behaviour of the cache store under concurrency (atomic increment support — Redis yes, file cache no). Also confirm the caching plugin's version, since this fix lives at the intersection of the two.

Sequencing

1. Pilot on one non-critical connector that uses both caching and rate limiting — that is the exact configuration this release touches.
2. Instrument: log remaining quota and 429 counts per connector for a week.
3. Promote to remaining connectors; move high-value vendors last.
4. Only then standardise the plugin set in a shared connector base class, so plugin ordering is defined once rather than per connector.

Operational Impact

Maintenance Small, single-purpose package with an active 2.x line and external contributors — a good maintenance signal for a dependency of this size. Cost of ownership is low in code terms but non-zero in attention: this release proves patch versions can alter observable throughput, so composer update should not be fully automated for connectors carrying quota-sensitive traffic. A pinned constraint plus a human glance at the changelog is the right posture.

Support Community-supported via GitHub issues, not a vendor with an SLA. Acceptable for outbound-call hygiene; not acceptable as the only control if a vendor quota breach has contractual or financial consequences. For those vendors, layer a server-side/business-level guard (fallback, queue, circuit breaker) so enforcement does not depend solely on a community plugin.

Scaling The decisive variable is the cache backend. With shared Redis, limits are global and behave correctly across autoscaled workers. With a per-instance store, each worker gets its own budget and you will breach vendor quotas at exactly the moment traffic grows — a scaling failure that appears as an upstream 429 storm, not as an infrastructure alarm. Validate this before any autoscaling work.

Failure modes

• Cache store unavailable → limit accounting degrades or fails open; decide explicitly whether that should hard-fail the call or proceed.
• Clock skew across workers → window boundaries drift; vendor sees more requests than intended.
• Under-counting (the bug just fixed) → upstream 429s that look like vendor flakiness and get misdiagnosed for weeks.
• Over-counting / plugin misordering with caching → self-inflicted throttling and latency on cached calls, which look like performance regressions rather than config errors.
• Silent behaviour change on patch upgrade → no error, just different volumes.

Ramp-up Low. A developer already comfortable with Saloon picks this up in well under a day. The learning curve is not the API — it is knowing each vendor's true quota and window semantics, which is a product/partnership question. Budget time for that, and for writing one integration test per connector that combines caching and rate limiting.