Mutex Bundle Laravel Package

Technical Evaluation

Architecture fit

• The package is a Symfony bundle, not a Laravel package. Its value-add is Symfony-specific: DI extension, service definitions, configuration tree, and container autowiring. In a Laravel app none of that executes — Laravel's container does not read *Bundle classes or DependencyInjection/Extension files. Release 3.0.0 reinforces this: the sole change is a "Symfony Package Upgrade," i.e. the maintenance effort in this release went entirely into the Symfony wrapper, which we would not use.
• The usable asset for a Laravel team remains the underlying mutex library (ixarlie/mutex) plus its storage adapters (Redis, MySQL GET_LOCK, PostgreSQL advisory locks, flock, semaphore). The bundle is packaging glue around that core, and 3.0.0 does not appear to have touched the core.
• Fit is therefore conditional and unchanged: adopt only if we need non-Redis mutex backends (DB-native locks where Redis is unavailable or undesirable). If Redis is already in the stack, Laravel's built-in Cache::lock() / Illuminate\Contracts\Cache\LockProvider covers the same ground with first-party support.

Integration feasibility

• Feasible but requires custom glue: register a Laravel service provider, bind a MutexFactory/adapter as a singleton, publish config as config/mutex.php, and expose a thin facade or injectable contract. Estimated effort remains 1–3 engineering days for a spike + wrapper, not a drop-in install.
• Do not let application code type-hint Ixarlie\MutexBundle\* classes; couple only to the core library interfaces so the Symfony wrapper can be dropped or swapped later. The 3.0.0 major bump is a concrete example of why: we get breakage signal from a component we never run.
• Composer risk increases with 3.0.0. A "Symfony Package Upgrade" as a major version implies tightened Symfony component constraints (dependency-injection, config, http-kernel). Laravel pins its own ranges of those same components, so a version conflict on install is now more likely, not less — verify with composer why-not and confirm the core ixarlie/mutex release line we intend to use has no coupling to Symfony 7.x.

Technical risk

• Adoption risk (high, unchanged): still a low-traffic package with near-zero dependents, single maintainer. 3.0.0 is one more release but not a production-validation signal; there is no evidence of downstream adoption growth.
• Abandonment risk (slightly improved, still material): this release confirms the maintainer is active as of the 3.0.0 tag, which is a positive update to the prior assessment. Bus factor remains one. MIT license still mitigates — we can fork/vendor — but that is a maintenance commitment we must budget for.
• Release-hygiene risk (new, medium): a major version bump whose entire changelog is a single dependency-upgrade PR, with no migration notes, no breaking-change description, and no linked issue detail. We cannot tell from the notes whether any public API changed or only constraints. Treat semver-major as "assume breakage until diffed," and read the 2.1.0...3.0.0 diff before pinning anything.
• Coupling risk (new): the bundle's release cadence now tracks Symfony majors. That is fine for Symfony shops and irrelevant-to-harmful for us — it produces breaking releases on someone else's schedule while adding zero Laravel capability. This argues for consuming ixarlie/mutex directly and pinning it, so Symfony upgrades upstream cannot force a rewrite of our wrapper.
• Semantic risk (medium, unchanged): mutex correctness is subtle — TTL expiry vs. work duration, lock ownership on release, clock skew across hosts. Bugs here surface as silent duplicate execution, not crashes.
• Overall: low ecosystem opportunity signal plus near-zero dependents still means limited community validation. 3.0.0 does not change that; it only confirms the project is not dead.

Key questions

1. Which concrete requirement is unmet by Cache::lock() that justifies a third-party mutex? (DB-only locking? Postgres advisory locks? Cross-language interop?)
2. Does 3.0.0 change any public API, or only Symfony dependency constraints? Confirm via the diff, not the changelog.
3. Is the core ixarlie/mutex library framework-agnostic and stable enough to use without the Symfony bundle — and which core version line should we pin so that 3.x-style Symfony churn cannot reach us?
4. Who owns maintenance if upstream goes quiet — do we vendor/fork, and is that acceptable?
5. What is the failure behavior on process kill mid-lock (stale lock window), and does the adapter guarantee ownership-safe release?
6. Do the adapters' connection semantics match our runtime (php-fpm vs. long-lived queue workers)?

Integration Approach

Stack fit

• Treat this as a library adoption, not a bundle adoption. Pull ixarlie/mutex (and only the specific adapter we need, e.g. the Postgres or MySQL adapter), not mutex-bundle, and explicitly do not track the bundle's 3.x line. Note in the decision record that 3.0.0 exists and was evaluated and rejected as irrelevant to a Laravel runtime.
• Wrap it behind a first-party Laravel contract (App\Contracts\DistributedMutex) so the implementation is replaceable by Cache::lock() or a future in-house driver without touching call sites.
• Where Redis exists, default to native Cache::lock(); use the mutex library only for the DB-lock path. This keeps the third-party surface to one adapter.

Migration path

1. Spike (timeboxed): install the core library, prove one adapter against a real DB in a scratch branch; confirm PHP version and dependency resolution against our composer.json. Explicitly test composer require ixarlie/mutex-bundle:^3.0 in a throwaway branch only to record the conflict surface — that result is the evidence for the "bundle, not library" decision.
2. Abstract: define the mutex contract and implement it twice — native cache lock and the ixarlie adapter — behind a config flag.
3. Pilot: enable on a single low-risk consumer (one queued job or one scheduled command) with instrumentation on acquisition failures and lock hold duration.
4. Decide: promote, or retire in favor of native locks and delete the dependency. The abstraction makes this a config change, not a refactor.

Compatibility

• Re-run the dependency audit against the 3.0.0 constraint set specifically; a Symfony-major bump is the most likely source of an unresolvable graph alongside Laravel's pins.
• Pin the core library to an exact minor range and document the pin rationale, since the upstream project's next breaking release may again be driven by a component we do not use.
• Verify adapter support for our DB engine and version (MySQL GET_LOCK semantics differ across versions; Postgres advisory locks require session affinity).
• Check whether the library depends on PSR interfaces we already implement (psr/log, psr/cache) — if so, binding is trivial.

Sequencing

• Dependency/version audit (now including a 3.0.0 conflict check) → adapter spike → contract + wrapper → pilot on one job → observability + rollout. Do not sequence this ahead of a native-lock baseline; establish the baseline first so the "why" is documented.

Operational Impact

Maintenance

• Low code churn expected (small API), but ownership burden is ours: no upstream SLA, near-zero dependents means no crowd-sourced bug discovery. Budget a named owner and a quarterly dependency-review slot.
• Version-pinning discipline is now mandatory. Add a standing check that our pinned core version has not drifted and that no transitive Symfony constraint has been introduced. If the maintainer ever folds the Symfony upgrade path into the core library, that is our trigger to fork.
• If forked, add CI, a security-watch subscription, and a documented upgrade path back to upstream.

Support

• No community support channel of consequence. Internal runbook required: how to diagnose a stuck lock, how to force-release, which tables/keys to inspect.
• On-call must be able to answer "is this lock held or leaked?" without reading vendor source — build a small artisan command for lock introspection early.
• Add a runbook note that upstream major releases (like 3.0.0) may be Symfony-only and should not trigger an upgrade cycle on our side. Without this, someone will "stay current" and pull a breaking bundle release we do not need.

Scaling

• Lock contention becomes a bottleneck under fan-out: DB-level locks (MySQL GET_LOCK, Postgres advisory) consume connections and can serialize hot paths. Model expected concurrency per lock key before broad rollout.
• Long-lived queue workers reuse connections — verify the adapter handles connection loss/reset without leaving orphaned locks.
• Multi-region or multi-cluster deployments: confirm the lock backend is genuinely shared; a per-node flock or per-connection advisory lock silently fails to provide mutual exclusion across hosts.

Failure modes

• Stale lock: holder dies or exceeds TTL → either permanent blockage (no TTL) or premature release allowing duplicate execution (TTL too short). Both are silent; require TTL > p99 job duration plus alerting on repeated acquisition timeouts.
• Duplicate execution: lock acquired without ownership verification on release — a holder whose TTL expired can delete another holder's lock. Confirm the adapter uses ownership tokens.
• Connection-scoped locks: MySQL GET_LOCK and Postgres advisory locks are session-bound; connection recycling can release a lock mid-critical-section. High-risk in pooled/worker environments.
• Deadlock / lock ordering: multiple lock keys acquired in inconsistent order produces hangs; enforce a canonical ordering convention.
• Dependency failure: upstream abandonment leaves an unpatched component in the critical path — mitigated by forking, not eliminated.
• Unplanned upgrade: a well-meaning dependency bump to a 3.x-style Symfony-driven major release breaks our wrapper with no functional benefit. Mitigate with an exact pin and a documented-upgrade policy.

Ramp-up

• Small API surface, so developer ramp-up is hours, not days. The real cost is conceptual: engineers must understand TTL/ownership/connection-affinity semantics before using it. Ship a one-page internal guidance doc and a code-review checklist for any new lock usage.
• Recommend a "mutex review" gate for the first several PRs using the abstraction, then relax.
• Add one line to the guidance doc on the bundle-vs-library distinction, so future engineers do not "helpfully" reintroduce the Symfony bundle.