Advisory Locker Laravel Package

Technical Evaluation

Architecture fit. fervo/advisory-locker is a thin abstraction over database-native advisory locks — PostgreSQL pg_advisory_lock*, MySQL GET_LOCK — built on Doctrine DBAL, not on Laravel's Eloquent/DB facade. That single fact drives the TPM-level read: in a conventional Eloquent-first Laravel service there is no Doctrine connection object to hand the library, so "adopting the package" really means standing up or binding a DBAL connection and then wrapping it. The underlying product need — a mutex keyed by an integer or name, acquired and released around a critical section — is a 50–150 line concern. The library's added value sits almost entirely in the per-driver branching, which is precisely the part you can least afford to have unmaintained. As a reference implementation it is useful; as a dependency it is weak.

Integration feasibility. Low-to-moderate effort, but gated on diligence, not engineering hours. Mechanically it is a service-provider binding, a driver config entry, and a try/finally around the critical section. The blockers are elsewhere: the package is dormant (1 star, 0 dependents, last release 2021-10-06), so there is no issue history to consult on the edge cases that actually cause incidents — session vs. transaction scoping, MySQL lock-name length limits, per-connection release semantics — and no evidence of testing against current databases. The first real gate is Composer resolution: a 2021-vintage DBAL wrapper will plausibly pin doctrine/dbal ^2.x, which conflicts with the 3.x/4.x required by modern Doctrine bundles and anything else in the tree. If that conflict exists, "integration" quietly becomes "fork."

Technical risk. High, concentrated in three places. (1) Abandonment on the correctness path — an unmaintained dependency guarding job deduplication fails silently, by not acquiring the lock, and surfaces as a duplicate-charge or duplicate-email defect weeks later. (2) Semantic divergence across drivers — Postgres locks are 64-bit bigint keys with shared/exclusive and blocking/non-blocking variants; MySQL's is a string-named lock with a timeout and per-connection release. A single interface is possible, but the failure modes differ sharply and a dormant package gives no assurance the implementations converge on our needs. (3) Connection topology — advisory locks are session-scoped, so PgBouncer in transaction pooling mode, RDS Proxy, a read/write splitter, or Octane's reused workers can hold a lock across unrelated requests or drop it mid-operation. That is the classic production incident with this technique, and an abstraction layer hides exactly the detail we need to reason about.

Key questions.

• Which DBAL major version does it require, and does that resolve against the rest of the tree? If not, is a fork acceptable?
• Are the locks session-scoped or transaction-scoped (pg_advisory_xact_lock is materially safer for web requests)?
• Is there a non-blocking or timeout-bounded acquire, or can a worker block indefinitely?
• What happens when the connection dies mid-critical-section — lock-leak detection, or deadlock on the next run?
• Are lock names hashed to integers, and what is the collision story?
• Does it ship tests, and against which database versions?

Integration Approach

Stack fit. Poor for an Eloquent-only Laravel codebase; reasonable only where Doctrine ORM/DBAL already exists (a legacy Symfony-style model layer, or a Laravel app that adopted Doctrine for domain persistence). If we are Eloquent-native, the defensible recommendation to stakeholders is do not adopt: implement the lock directly with DB::selectOne('SELECT pg_try_advisory_lock(?)', [$key]) or the MySQL GET_LOCK equivalent behind a small first-party interface. That is roughly a day of work, removes a dead dependency, and — crucially — makes session scoping explicit, which is the whole ballgame.

Migration path. If we proceed anyway: (1) spike on a throwaway branch with composer require furyo/advisory-locker and record the exact PHP/DBAL constraints it forces — abort if it drags DBAL backwards; (2) if resolution fails, fork into an internal namespace via a path or VCS repository, bump DBAL to the modern major, run the package's tests, and add coverage for the drivers we actually use; (3) bind a single DBAL connection derived from Laravel's existing PDO so exactly one connection identity holds locks — never a second pool; (4) wrap acquisition in a first-party LockManager::withLock(string $name, int $ttl, Closure $fn) so no call site ever touches the vendor API. That last step is the insulation that turns the vendor into an afternoon-swappable implementation detail.

Compatibility. Verify against the real matrix, not the CI-default matrix: PHP 8.2/8.3 (a 2021 release barely overlaps these), PostgreSQL 14–16, MySQL 8, and — critically — the production connection pooler. Advisory locks pass against a direct connection and fail under PgBouncer transaction pooling; test in the topology we ship. Octane adds a second wrinkle: persistent workers mean a lock leaked by an uncaught exception survives into subsequent jobs.

Sequencing. Behind a feature flag on one low-stakes job first (a cache warmer, not billing). Order: spike → fork if needed → internal service wrapper → single-connection binding → production-like topology test → flagged rollout → only then expand to higher-stakes call sites. Budget half a day for the spike and 2–3 days end-to-end if a fork plus test coverage is required. Frame this to leadership as a one-week spike to settle which lock primitive we standardize on, not as a package-install task.

Operational Impact

Maintenance. Upstream cadence is effectively zero since October 2021 — we are the maintainer. Treat any fork as first-party code: we own the CI matrix, the database-version bumps, and the eventual DBAL-major rebase. The annual cost is small but non-zero and, more importantly, unpredictable — it lands as an outage-adjacent scramble rather than planned roadmap work. Assign a named internal owner at the moment of adoption or don't adopt.

Support. No meaningful external support: no maintainer responsiveness guarantee, no package-specific knowledge base, no community to sanity-check an anomalous failure against. Escalation is internal-only, which is acceptable for a ~100-line concern and unacceptable for anything customer-facing on day one.

Scaling. Advisory locks are cheap and scale well for low-frequency, coarse-grained mutual exclusion — nightly jobs, one-per-tenant backfills, deploy-time migrations, single-flight cache refreshes. Tens of locks per minute, not thousands per second. They serialize hard: a hot, highly contended key becomes a queue with worse ergonomics than an actual queue. Document throughput expectations alongside the lock primitive so product teams don't reach for it in the wrong place.

Failure modes. The ones that matter are silent, which is what makes this a TPM concern rather than a pure engineering one: a lock not acquired because the connection was pooled, a lock held past its critical section because a finally was skipped, a deadlock on the next run after a connection kill, a hash collision on a business-identity key. Each presents as a duplicate side effect — two emails, two charges, two invoices — and each is hard to reproduce locally. Mitigations are non-negotiable: mandatory timeout-bounded acquire, structured logging on acquire/contend/release, an alert on lock-wait duration, and integration tests that run against the production topology.

Ramp-up. Low technical ramp-up (an afternoon to read and understand), but a real conceptual ramp-up: engineers must internalize session-vs-transaction scoping, connection lifecycle under pooling and Octane, and the difference between "I called acquire" and "I hold the lock." Budget a short internal write-up and a working example before any second team uses the pattern. The honest organizational takeaway: the technique is worth adopting and cheap to prototype; the artifact is a reference implementation to vendor or reimplement, and the decision in front of us this week is which lock primitive we standardize on — Cache::lock(), a first-party DB lock, or a managed service — not whether to install this package.