Filament Record Lock Laravel Package

Technical Evaluation

Architecture fit. This package adds application-level pessimistic locking to Filament 5 edit surfaces: a HasLocks model trait, UsesResourceLock / UsesSimpleResourceLock page traits, a heartbeat renewal loop, and server-side refusal of saves from pages that no longer hold the lock. That last point is the architecturally significant one — the lock is not a database row lock (SELECT ... FOR UPDATE), it is an advisory lock enforced in application code. The UI notice is convenience; the save-time guard is the correctness mechanism. TPM framing: this is a concurrent-editing UX and data-loss-prevention feature, not a transactional integrity control. Teams must not assume it protects against writes from queues, imports, APIs, or console commands.

Integration feasibility. Adoption cost looks low and localized: add a trait to models, swap a page trait on Edit pages and modal edits, run the migration, schedule record-lock:prune. Three things raise the real effort estimate: (1) the authorization gate behind "Unlock and edit" is a policy decision we must own, not a default we inherit; (2) the "Record locks" manager page is suppressed on tenant panels unless scopeManagerQuery() is implemented, so multi-tenant installs need tenant scoping written before the admin surface is usable; (3) kenepa/resource-lock API compatibility is explicitly qualified "where it makes sense," so an existing install is a migration project, not a composer bump — budget a spike against the README migration section.

Technical risk. Moderate, concentrated in four areas. Version coupling: a hard dependency on Filament 5 plus a v1.0.0 package means two young surfaces moving at once; Filament minor releases have historically changed page lifecycle and action APIs. Driver sensitivity: the release notes themselves show write-path SQL that behaved differently on MySQL (affected-row counts) and PostgreSQL (string-key eager loading) — this package's correctness is driver- and version-dependent, so our CI matrix must match production, including whether SQLite is viable for local dev. Best-effort release: navigator.sendBeacon on leave is unreliable (backgrounded tabs, mobile, crashes, network loss), so lock leakage is expected, not exceptional; the prune command and heartbeat expiry are the actual backstop and their TTL/grace values are undocumented here. Polymorphic owner/subject records: "unknown morph types do not crash the manager" is a good defensive fix but confirms orphaned lock rows are a real class of residue after model renames or refactors.

Positive signals worth logging: #[Locked] on lock state closes a Livewire client-tampering vector, takeOver() is atomic, and own-save no longer marks the page stale — this reads like a team that has done a hardening pass, not a first cut.

Key questions.

• Are lock TTL, heartbeat interval, and grace period configurable, and what are the defaults? A short TTL with a slow poll interval produces false takeovers; a long TTL produces blocked users.
• What is the coverage matrix — Create pages, relation managers, nested/inline repeaters, bulk edit actions, custom non-resource pages? Only Edit pages and modal edits are named.
• Which database drivers and versions are in the supported test matrix? Is SQLite supported for local/dev?
• Is the prune command safe under multiple app nodes (onOneServer), and what retention does it enforce?
• What governs the "Unlock and edit" permission — a Laravel policy, a Filament permission, or panel access? Who is intended to force-unlock, and is takeover auditable via RecordLockTakenOver?
• Semver and support policy: how tightly will releases track Filament 5 minors, and what is the security disclosure path?
• License terms and maintainer/bus-factor posture.

Integration Approach

Stack fit. Assumes Laravel with Filament 5 panels, Livewire, and a scheduler. Keys: integer, UUID, ULID are covered — a good match for a mixed legacy/modern model estate; natural string keys and composite keys are unconfirmed and should be treated as out of scope until verified. The configurable table and connection is a genuine architectural lever: putting the locks table on a dedicated connection isolates poll and heartbeat write traffic from the primary transactional database.

Migration path. From kenepa/resource-lock, plan a three-step path: read the README migration section, run a timeboxed spike porting one high-contention resource, then roll out behind the model trait one domain at a time. Compatibility only "where it makes sense" means dual-running the two packages on separate resources is plausible but should be validated, not assumed. From no locking at all, the path is simpler but the sequencing matters more.

Compatibility. The binding constraints are Filament 5, PHP version, and database driver/version. Treat the driver as a first-class compatibility item given the MySQL and PostgreSQL fixes in this release. Verify behaviour with UUID/ULID keys on PostgreSQL specifically before trusting the fix.

Sequencing. (1) Spike on one resource with real concurrency. (2) Decide and implement the takeover permission model and tenant scoping. (3) Pin the CI matrix to production driver versions. (4) Ship to an internal/admin-only panel cohort and instrument lock contention. (5) Roll out by resource, highest-collision first — the resources with the most concurrent editors yield the benefit soonest and expose problems fastest. (6) Publish an internal runbook before broad enablement.

Operational Impact

Maintenance. Ongoing obligations: track Filament 5 releases against a v1.0.0 dependency, keep the prune schedule healthy, and re-verify driver-specific behaviour on database upgrades. The locks table grows continuously and needs retention ownership. Budget for a small but permanent line item, not a one-off.

Support. Expect a new, recurring ticket class: "the record is locked and I can't edit it." Each instance needs a triage path — is it a live editor, a leaked lock awaiting prune, or a dead session? The read-only manager page and ReleaseLockAction / ReleaseLocksBulkAction are the support tooling; the manager's absence on unscoped tenant panels is a support-visibility gap that must be closed before go-live. Also expect confusion between "read-only view" and "someone else is editing" — worth a short internal doc.

Scaling. Cost scales with concurrent editors, not records: one polling client per open edit page against a heartbeat endpoint, plus a write per renewal. Model this against peak concurrency before broad rollout, and prefer the dedicated connection if edit concurrency is high. Deploy windows are a predictable spike — every client re-establishes at once, and the heartbeat's "re-create rows with the page token" behaviour is exactly the recovery path that will be exercised.

Failure modes. (a) Stale lock blocks a user — mitigated by prune and takeover; needs an SLA. (b) Dropped beacon on tab close or mobile — expected; prune is the backstop. (c) Heartbeat endpoint degraded — locks appear held or lapse, triggering false takeovers and refused saves; this is the highest-blast-radius failure and deserves monitoring and an alert. (d) Orphaned polymorphic rows after a model rename or refactor. (e) Scheduler not running in an environment (no schedule:run cron) — silently defeats pruning and accumulates dead locks. (f) Save-time refusal surfacing as an unexplained error rather than a clear message — verify the UX on the refusal path, not just the happy path.

Ramp-up. Low for developers (traits plus migration) but non-zero for the org: the permission model for force-unlock, the tenant-scoping requirement on the manager, and the support runbook are all product and process work that ships alongside the code. Given the hardening evident in this release, it is reasonable to pilot now — with the explicit caveat that a v1.0.0 dependency on a new major Filament version is a watch item rather than a settled platform bet.