Lock Laravel Package

Technical Evaluation

Architecture fit: Still purpose-built for RoadRunner's long-running worker model, and the architectural fit is now materially stronger because 1.2.0 adds first-class RoadRunner v3 support. RR v3 is the current major line, so this release moves the package from "aligned with a legacy runtime" to "aligned with the supported runtime." Two changes drive the re-evaluation:

• Package rename: roadrunner-php/lock → roadrunner/lock (Composer package identity change, consistent with the RoadRunner org's v3-era naming).
• RoadRunner v3 compatibility: the lock plugin contract, rr.yaml schema, and worker/plugin lifecycle semantics differ between RR v2 and v3.

No internal locking abstraction changes are documented, so the conceptual model (acquire/release a named lock inside a worker) is unchanged. However, the runtime contract underneath it has moved, which is where integration risk concentrates.

Integration feasibility: Feasible but no longer a no-op upgrade. This is a breaking change at the dependency-management layer, and potentially at the configuration layer:

• Composer: consuming code must composer require roadrunner/lock; the old package name should be treated as superseded. Existing composer.json constraints on roadrunner-php/lock will not resolve to 1.2.0.
• Config: applications on RR v2 must either stay pinned or migrate both RoadRunner and this package together. An RR v2 runtime with a 1.2.0 package (or vice versa) is an unsupported combination and must be explicitly blocked by version constraints.
• Release gap: the previous assessment was written against 1.0.1; this is 1.2.0, so 1.1.0 was never assessed. Review the 1.1.0 diff before approving, since it may carry intermediate API changes not described in these notes.

Technical risk: Medium (upgraded from Low). Justification:

• Not a docs-only release this time — there are functional/compatibility changes (new runtime major version) and a breaking packaging change (rename).
• The rename is low-effort to remediate but high-blast-radius if missed: dependency resolution failures, CI breakage, and stale internal documentation referencing the old package name.
• The RR v3 support is additive if the package retains dual compatibility; if it drops RR v2, every existing deployment must migrate the runtime. The release notes do not state whether RR v2 remains supported — this is the single most important unknown.
• No stated API/deprecation changes to lock acquisition/release, which limits risk to configuration and packaging rather than application logic.

Key questions:

1. Does roadrunner/lock 1.2.0 retain RR v2 compatibility, or does it require RR v3 (i.e., is this a hard cutoff)? What is the exact supported version matrix (package × RoadRunner × PHP × Laravel)?
2. Did the rename also change the PHP namespace (e.g., RoadRunnerLock\... vs. RoadRunner\Lock\...) or only the Composer package name? This determines whether use statements must be rewritten.
3. Does the old package roadrunner-php/lock receive a final release with a replace/provide alias, or must every consumer update composer.json manually?
4. Are there changes to the rr.yaml lock plugin schema in v3 (driver keys, Redis config, DSN format) that invalidate the configuration snippet currently in our runbook?
5. What shipped in 1.1.0, which was never assessed? Any API, deprecation, or minimum-version changes there?
6. Which applications in our portfolio are actually on RoadRunner today, and of those, how many are still on RR v2?

Integration Approach

Stack fit: Compatible with the Laravel/PHP stack, contingent on RoadRunner being present and on which RR major version. Fit is now version-sensitive rather than unconditional: the package is aligned to RR v3, and Laravel-side integration remains via the service container / a service provider. PHP and Laravel minimum versions should be re-verified against 1.2.0's composer.json — do not assume the prior Laravel 8.x–10.x / PHP 8.0+ statement still holds, since RR v3-era tooling typically raises the PHP floor.

Migration path:

• Existing users on RR v2 (recommended default): pin to the last RR-v2-compatible line and defer. Add an explicit upper bound in composer.json so an unattended composer update cannot pull 1.2.0 into an RR v2 environment. Track the RR v3 migration as its own work item.
• Existing users moving to RR v3: upgrade as a single coordinated change — RoadRunner server to v3, rr.yaml to the v3 schema, then the package:
  1. Update composer.json: remove roadrunner-php/lock, add roadrunner/lock at ^1.2.
  2. Rewrite use statements only if the namespace changed (confirm via key question 2).
  3. Re-verify the lock plugin block in rr.yaml against the v3 schema and driver options.
  4. Run the existing lock-contention tests against RR v3 in staging before production.
• New adopters: start directly on roadrunner/lock + RR v3; there is no reason to onboard onto the superseded combination.
• Abandoned-name hygiene: grep the organization for roadrunner-php/lock in composer.json files, Dockerfiles, CI configs, runbooks, and internal wikis, and update in one sweep.

Compatibility: Backward compatible at the lock API level, breaking at the packaging level, and conditionally breaking at the runtime level. Treat RR v2 → v3 as a platform upgrade with its own test plan, not as a dependency bump. The prior claim of Laravel 8.x–10.x / PHP 8.0+ compatibility must be re-validated, not carried forward.

Sequencing:

1. Inventory: list every service using RoadRunner, its RR major version, and its current lock package constraint.
2. Freeze: add upper bounds on the old package name for all RR v2 services to prevent accidental adoption of 1.2.0.
3. Assess 1.1.0: review the unassessed diff for intermediate changes.
4. Validate the matrix: confirm the 1.2.0 support matrix from the maintainer (or from composer.json + CI config) and record it in the internal dependency policy.
5. Pilot: migrate one low-risk service end-to-end (RR v3 + rr.yaml v3 schema + roadrunner/lock), including lock-contention and orphan-lock scenarios.
6. Document: publish the v3 rr.yaml lock snippet and the updated package name in the runbook before wider rollout.
7. Roll out: remaining services in waves, each with a rollback pin to the last known-good package/runtime pair.

Operational Impact

Maintenance: Slightly increased near-term, lower long-term. Near-term work is administrative (constraint updates, package-name sweep, config revalidation). Long-term, being on RR v3 keeps the package on a supported runtime line, which reduces the risk of running an unmaintained combination. Expect a one-time bump in dependency-review load while the v2/v3 split exists, since two supported configurations must be tracked.

Support: Neutral to slightly negative in the short term, then improved. The rename is a predictable source of confusion — support requests referencing "which package do I install?" and copy-pasted v2 rr.yaml snippets on v3 runtimes should be anticipated. Mitigate by publishing an internal one-page migration note and updating the existing runbook snippet; do not rely on upstream docs alone for the config delta.

Scaling: No change to the scaling model. Lock performance remains a function of the backend driver (Redis/filesystem) and RoadRunner's stability, not of the package. Scaling review is unchanged, with one caveat: any RR v3 performance/tuning differences (worker pool sizing, plugin restart behavior) should be validated once in the pilot rather than assumed equivalent to v2.

Failure modes:

• Version skew (new, highest likelihood): package 1.2.0 running against an RR v2 server, or an RR v3 server with a v2-era rr.yaml lock block. Symptom is plugin initialization failure or silent lock misbehavior. Mitigation: explicit composer constraints plus a startup assertion in staging.
• Dependency resolution failure (new): CI fails after the rename because a transitive or root constraint still references roadrunner-php/lock. Mitigation: repository-wide grep; check for replace aliasing upstream.
• Namespace mismatch (conditional, new): unresolved class errors if the namespace changed and use statements were not updated. Mitigation: confirm before pilot; static analysis in CI will catch it.
• Orphaned locks on worker crash (pre-existing): unchanged in nature, but re-test under RR v3, since worker lifecycle/restart semantics differ and may alter how locks are released on abrupt termination.
• Documentation drift (pre-existing): the previously improved docs are now partly stale for v3 config. Treat the runbook as the source of truth and update it deliberately.
• Abandoned-package exposure (new): if the old package name stops receiving patches, any service pinned to it accrues unpatched risk over time. Track as a dated deprecation item rather than an open-ended pin.

Ramp-up:

• For developers: Low, provided the namespace is unchanged — the lock usage pattern is identical:

  use RoadRunner\Lock\Lock; // confirm namespace against 1.2.0
  
  $lock = app(Lock::class);
  $lock->acquire('job:process_order_123');
  try {
      // Critical section
  } finally {
      $lock->release('job:process_order_123');
  }
  

  If the namespace did change, that is a mechanical but repo-wide edit; scope it as a small chore, not a feature.
• For ops: Moderate for the v3 move — the rr.yaml schema changed, so the existing lock plugin block must be re-derived from v3 docs rather than copied. Budget a half-day for one engineer to validate drivers (Redis), credentials handling, and lock behavior under worker restart, then templatize the validated snippet for the remaining services.

Recommendation: Treat 1.2.0 as a platform-alignment release, not a patch. Approve adoption only as part of an explicit RoadRunner v3 migration, and immediately constrain all RR v2 services to the last v2-compatible release to prevent uncontrolled adoption via routine dependency updates.