Filament Resource Lock Laravel Package

Product Decisions This Supports

• Build vs. buy for concurrent-edit safety. The core capability — preventing two admins from silently overwriting each other on the same record — is a real, recurring defect class in back-office tools. This package reduces the decision to "install and wire two traits" versus a custom lock table + polling endpoint + UI states (roughly 1–2 weeks of engineering). Use it to settle the build-vs-buy question quickly rather than deferring the feature another quarter.
• Roadmap scoping of "collaboration" features. The package defines a concrete, pessimistic-locking scope: lock ownership, heartbeat/TTL, handoff requests, save-and-unlock. That is a very different (and far cheaper) commitment than real-time co-editing. It lets you ship a defensible collaboration story without committing to CRDT/OT work.
• Audit trail and rollback as a support-ops lever. Optional snapshots with per-field diffs, a versioned history panel, and selective rollback change the support model: a rep can restore three fields from v4 instead of asking engineering to reconstruct data from backups. This informs whether "audit history" is a differentiated roadmap item or a commodity you buy.
• Infrastructure spend decisions. Polling vs. Laravel Echo push is a cost/architecture fork: polling keeps you on the existing stack; broadcast pulls in Reverb/Pusher/Ably, websocket ops, and private-channel auth. The config flag makes this a reversible product decision rather than a one-way door.
• Storage and data-retention policy. Database vs. Redis for lock state, plus audit.max_entries_per_resource (default 500) and retention toggles, surface a decision product usually forgets: how much edit history do we keep, and is it a system of record or a convenience cache?
• Permission model design. save_and_unlock and ask_to_unblock are gated by named permissions with an escape hatch (null skips policy checks). This forces an explicit answer to "who is allowed to take a record away from someone else?" — a governance question, not just a UI one.
• Platform version commitment. The package targets Filament v5 / Laravel 12–13 / PHP 8.3+. Adopting it is a de facto vote for the v5 upgrade timeline, and the upgrade becomes a prerequisite in your dependency graph.
• Localization roadmap input. Shipped locales are en and ru only; if your admin panel serves other markets, translation work is an unbudgeted line item you can now see and price.

When to Consider This Package

Consider it when:

• You are already on (or actively migrating to) Filament v5 with PHP 8.3+ and Laravel 12/13. There is no value here for v4 or earlier.
• Your admin panel has multiple humans editing the same records — ops, support, finance, catalog managers — and you have seen (or expect) lost-update incidents, duplicate-work tickets, or "who changed this?" questions.
• Concurrency is low to moderate (tens of concurrent editors per resource, not thousands per second). Pessimistic locking is the wrong shape for high-contention hot records.
• You want audit history with a usable UI — field-level diffs, a create badge, selective rollback from a slide-over — without building a diff renderer per field type. The built-in renderers (numeric bars, select badges, toggles, rich text, key-value) are genuinely the expensive part to replicate.
• You can absorb small-vendor dependency risk: you have the appetite to fork or vendor a ~MIT package if the maintainer disappears, and you will write your own integration tests around it.
• You are willing to tune configuration deliberately — TTL, release grace, stale-release guard, and Echo channel setup all have defaults that must match your session and APP_URL realities.

Look elsewhere (or build) when:

• You need true simultaneous co-editing (multiple cursors, live field sync). This is a lock, not collaboration — it deliberately blocks the second user. Expect stakeholder disappointment if the ask was "Google Docs for our admin panel."
• You need compliance-grade, immutable audit (SOC 2, ISO, tamper-evident logs, SIEM export, long retention). A pruned 500-entry-per-resource table with rollback is an operational convenience, not an audit control. Pair with or replace by a dedicated auditing/event-sourcing approach.
• Your edit pages override save() or afterCreate() with custom persistence. The README is explicit that the trait's wrapper is bypassed and you must call the bridge methods manually — and that no framework mechanism can fix this. Custom save flows (multi-step wizards, side-effecting saves, queued writes) raise integration cost and silent-audit-gap risk materially.
• You only need optimistic concurrency: a lock_version column and a 409 conflict on stale saves is a few hours of work, has no shared state to operate, and never leaves a record locked because someone's laptop slept.
• You require vendor support, an SLA, or a security review trail. Seven stars, zero dependents, and a single maintainer mean you are the support contract.
• Your broadcast stack isn't real — no window.Echo, no Reverb/Pusher, no private-channel auth. Broadcast mode is not a config toggle in practice; it is a project.
• You need locales beyond en/ru, or per-field-level permissions, or non-Filament surfaces (public forms, API writes) — the package covers Filament EditRecord pages only.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring class of data-integrity incidents where two people edit the same record and one person's work is silently lost, plus a slow, engineering-dependent process for undoing bad edits. This MIT-licensed package closes both gaps inside our admin panel: it shows who is editing a record, blocks accidental overwrites, lets an editor formally request or hand off the record, and keeps a versioned history with per-field diffs and one-click restore of selected fields. Integration is a composer install, a migration, and two lines on each edit page — days, not weeks — and there is no license fee or vendor lock-in. The trade-off is a small, early-stage open-source dependency tied to Filament v5; we mitigate that with our own tests and a fork-ready posture, and the fallback (build a minimal lock table ourselves) is a known, bounded cost.

For engineering (what you're actually signing up for):

• Add HasResourceLocks to models, InteractsWithResourceLock to EditRecord pages, HasResourceAudit to edit and create pages, and the table columns for lock state and creator.
• Run filament-resource-lock:install + migrate; it publishes config, migrations, an Echo bootstrap file, and injects an import into resources/js/bootstrap.js.
• Choose heartbeat (polling, ~10s interval, zero new infra) or broadcast (Echo private channels, lower latency, new infra + window.Echo + correct APP_URL for the signed release route). Start with heartbeat; treat broadcast as a later optimization.
• Tune ttl_seconds, release_grace_seconds, and stale_soft_release_ignore_seconds against real user behavior (tab close, sleep, SPA navigation). Defaults are a starting point, not a spec.
• Audit correctness is your responsibility where save() or afterCreate() is overridden — call syncResourceAuditBeforeSave() / syncResourceAuditAfterSave() / syncResourceAuditAfterCreate() explicitly. Add a test that fails if an audit row is missing after a custom save path.
• Custom Filament fields need HasAuditDiffPreview with an auditDiffPreviewUsing() callback for a readable diff; that callback renders trusted HTML — escape all user-controlled fragments.
• Risk posture to state plainly: 7 stars, 0 dependents, single maintainer, no announced SLA, pinned to Filament v5 (itself young). Mitigations: pin the version, wrap integration in our own feature/integration tests, isolate usage behind a small internal adapter so a swap is a one-file change, and pre-agree the build-it-yourself fallback (~a lock table, a heartbeat endpoint, and disabled form state). Treat audit-vs-compliance as a separate decision: this gives operators a restore button, not an audit control — if compliance is in scope, budget for a dedicated solution in parallel.