Semaphore Laravel Package

Product Decisions This Supports

• Build vs. buy for concurrency control. The decision this package most directly unblocks is whether to hand-roll locking/throttling logic in application code or adopt a maintained primitive. Buying means accepting a Symfony-core dependency; building means owning deadlock handling, TTL expiry, and store abstraction forever. For most teams the "buy" case is strong because the code is already in the dependency tree — Laravel pulls symfony/lock transitively, and symfony/semaphore sits in the same family. The real decision is usually not "adopt Symfony" but "do we need a counting semaphore on top of what Cache::lock() already gives us?"
• Feature scoping: bounded concurrency vs. exclusive locking. This is the key product distinction. Laravel's Cache::lock() grants exclusive access (one holder). A semaphore grants N concurrent permits. That difference unlocks a distinct feature class:
  • Capping concurrent outbound calls to a rate-limited third party (payments, carrier APIs, LLM providers) at N in flight rather than N per second.
  • Protecting finite resource pools: connection slots, license seats, GPU/worker capacity, per-tenant export jobs.
  • Serializing writes to shared aggregates while still allowing read parallelism. If the roadmap item is "stop duplicate work / stop hammering a vendor," this is the right primitive. If the roadmap item is "only one job should run at a time," a plain lock is simpler and this package is over-scoped.
• Reliability roadmap input. Concurrency bugs are the class of defect that surfaces as intermittent, unreproducible, and expensive — duplicate charges, double-shipped inventory, corrupted counters. Framing adoption as defect-class elimination rather than feature delivery is the highest-leverage way to sequence this work, because it competes for engineering time against visible features and will otherwise lose.
• Platform/infrastructure decisions. Choosing a store is a product decision, not just a technical one: filesystem locks constrain you to single-server deployments and quietly break the moment you scale horizontally or move to containers with ephemeral disks. If the roadmap includes autoscaling, multi-region, or queue-worker fleets, Redis (or a compatible store) is effectively mandatory — which makes this a dependency on the caching/queue infrastructure roadmap, and should be sequenced alongside it, not after.
• Operational readiness decisions. Semaphores introduce a new failure mode with customer-visible consequences: a leaked permit degrades into an outage (all workers blocked waiting). That requires a product decision on degraded behavior — fail fast with an error, or degrade to unprotected execution with an alert — plus monitoring for permit starvation. Budget for this; it is not free with adoption.
• Prioritizing the version/security migration. The tracked line is a pre-release (8.1.0-BETA3) while a [SECURITY]-tagged patch landed on the long-EOL 5.4 branch. For a PM this is a roadmap forcing function: any surface still on the legacy line is unsupported and needs a dated migration commitment, and the beta pin needs a written exit criterion to stable. Treat this as scheduled risk retirement, not routine maintenance.

When to Consider This Package

Consider it when:

• You need counting concurrency (N permits), not just mutual exclusion — most Laravel apps that reach for this actually need Cache::lock() and should start there.
• The application is multi-process by design: queue workers, cron, Horizon, or multiple app servers. Single-process deployments gain nothing meaningful.
• There is a concrete, monetizable or costly race already in the backlog — duplicate charges, oversold inventory, vendor rate-limit breaches — rather than a hypothetical one.
• A distributed store is available or planned: Redis (including cluster/sentinel DSNs, which gained support in 6.4/7.2) or a PDO-backed store. No store strategy means no adoption.
• You are already on a supported Symfony line (6.4+/7.x/8.x) and PHP 8.1+/8.4 depending on branch, and the team accepts Symfony's normal release cadence.
• You want a framework-agnostic, MIT-licensed primitive that will not tie the codebase to a niche vendor package.

Look elsewhere (or defer) when:

• You only need single-flight locking — use Laravel's Cache::lock() / WithoutOverlapping middleware. Adopting this adds surface area for no added capability.
• There is no distributed store and no plan to add one; filesystem semaphores in containerized environments are a trap.
• You need automatic lease renewal for long-running jobs. This package does not renew leases automatically; you would layer that on, or evaluate a Redis-native approach with explicit SET NX EX + watchdog.
• The workload is very high throughput and lock round-trips are on the hot path; per-operation latency and contention must be benchmarked before commitment.
• The team cannot own the operational burden (deadlock monitoring, stale-key detection, alerting on permit starvation). Unowned concurrency primitives become outages.
• You are pinned to 5.4 or another EOL line — that is a migration project, not an adoption project.

Signal caveats: 37 stars and 0 dependents are artifacts of Symfony's split-repository publishing model, not health indicators — do not use them as a maturity argument in either direction. The date on the latest release (2026-10-15) is a data-quality flag worth confirming before quoting version numbers to stakeholders.

How to Pitch It (Stakeholders)

For executives — one paragraph: We can eliminate a class of intermittent, expensive production bugs — duplicate charges, oversold inventory, vendor rate-limit breaches — by adopting a small, MIT-licensed, battle-tested concurrency primitive that is already adjacent to our dependency tree rather than building and maintaining one ourselves. The real cost is not the package; it is the Redis dependency, the operational monitoring, and a version-hygiene cleanup on a legacy branch. Recommend approving it scoped to one named race condition with a measured before/after, not as a platform-wide rollout.

For engineering — the substance: Use it only where you need N concurrent permits, not exclusive access; if you need exclusive access, Cache::lock() already covers you and this is redundant. Back it with Redis, not the filesystem, and treat the store choice as an architectural commitment. Wrap acquire()/release() in finally, set TTLs on every permit, and alert on permit starvation — a leaked semaphore is an outage, not a slowdown. Name keys narrowly (inventory_{productId}, not inventory) to avoid global contention. There is no automatic lease renewal, so long-running jobs need explicit handling. Finally, confirm which release line we pin, get the advisory ID and patched-version list for the [SECURITY] release on the 5.4 branch, and write an exit criterion from the 8.1.0-BETA3 pre-release to stable before this touches production.

Ask: one sprint to prove it against a single race condition, with Redis, monitoring, and a stable-version pin as exit criteria.