Product Decisions This Supports
- Which third-party integrations we can offer, and at what fidelity. Every vendor publishes an outbound quota (e.g. 60 req/min per API key). This package turns that quota into a config file, which is the artifact you actually need in a roadmap conversation: it produces a defensible answer to "can we do real-time sync with Vendor X?" versus "we can promise sync within 15 minutes." It converts a marketing question into arithmetic.
- Build vs. buy for an "integrations platform" layer. Throttling is one of the first things every growing SaaS rebuilds badly. This package is the borrow/buy option in that comparison — cheap, config-driven, cache-backed — and it sets the baseline scope for an internal
OutboundHttp client if you choose to build.
- Buying higher quota tiers vs. spending engineering time. If the throttle math says we can't hit the product promise at the current tier, the decision is concrete: pay the vendor, shard requests across multiple API keys (and therefore multiple throttle buckets), or degrade the feature. This package makes that trade-off visible rather than discovered in production.
- Queue architecture and capacity planning. Because the limits hold across processes via a shared cache/Redis store, it directly informs how many Horizon workers we can safely run per integration, and whether one tenant's historical backfill can starve everyone else's syncs (multi-tenant fairness is a product promise, not just an ops concern).
- Reliability and churn risk. 429s, temporary vendor bans, and retry storms show up as "my data isn't updating" tickets and dunning churn. A shared outbound limiter is the cheapest mitigation available before you invest in circuit breakers and per-vendor dashboards.
- Per-customer API key models (enterprise/self-hosted integrations). Deciding whether limits are keyed per host or per credential is a product decision about tenant isolation, and it has to be answered before you sell the feature, not after.
When to Consider This Package
Adopt (or, more likely, copy) it when all of these hold:
- You're on Laravel/PHP and outbound calls already flow through Guzzle.
- Several processes hit the same vendor API — Horizon workers, multiple pods, scheduled commands — so an in-process counter isn't enough and you need the shared Laravel cache/Redis store this wrapper provides.
- You want limits config-driven and changeable without a deploy, because vendor quotas and our tier change more often than our code.
- The calls are background/job or CLI work, where waiting a few hundred milliseconds for a slot is acceptable. Smoothing beats failing fast in that context.
Look elsewhere (or just build it) when:
- Package health is a blocker. Zero stars, zero dependents, single maintainer, and — verify before you commit — Guzzle 6 vs. 7 and Laravel 10/11 support. If it doesn't install cleanly on your stack, the honest move is to fork it, vendor the middleware, or depend on the underlying
guzzle-advanced-throttle directly. This is a ~1-day internalization, not a strategic dependency.
- You need more than pacing. No
Retry-After handling, no circuit breaking, no per-call metrics, no dynamic limits derived from X-RateLimit-Remaining headers. If the roadmap includes "vendor API health dashboard" or "auto-adjust to server-side quota," this is only one ingredient.
- The call is in a user-facing synchronous request path. Sleeping inside a web request to respect a quota is a latency anti-pattern; use Laravel's built-in
RateLimiter or queue the work instead.
- You're on a single process with one caller, in which case a few lines of middleware or
Http::retry(...) is sufficient and a dependency is pure overhead.
Due diligence gate: read the source (it's thin), confirm supported PHP/Guzzle/Laravel versions and cache drivers, check open issues and last commit date, and pin it. Treat it as a reference implementation, not a maintained vendor.
How to Pitch It (Stakeholders)
Executives (one paragraph): "It's a traffic cop for our outbound API calls. Instead of discovering a vendor's rate limit by getting blocked, we encode each vendor's published limit in config and the app self-paces. That protects us from 429 storms, temporary bans, and the support tickets and churn that follow, and it gives us real numbers for 'can we promise real-time sync?' But I don't recommend it as a strategic dependency — it's a tiny, unmaintained community package with no ecosystem. I recommend a two-day spike: wrap it behind our own outbound-HTTP interface, instrument it, and if it works we own a fork we can maintain ourselves."
Engineering (the specifics): Thin Laravel service provider around a Guzzle middleware. Rules are declared per host (and per route/pattern) with max-requests-in-a-period; the counter lives in Laravel's cache/Redis, so limits are shared across Horizon workers and pods rather than per process. It attaches to the container-resolved Guzzle client, so integration code changes are minimal. Costs: one config file, a client swap, and queue sizing — blocking waits consume a worker slot, so capacity is throughput × wait. Watch for cache TTL/clock skew edge cases at window boundaries, and add your own logging of wait time and 429 rate since the package ships no metrics. Ask: 1–2 day spike, behind an interface, with the underlying guzzle-advanced-throttle as the fallback if the wrapper is stale.