Filament Resource Lock Laravel Package

Technical Evaluation

Architecture Fit

• Filament v5 Native Integration: Designed specifically for Filament’s EditRecord pages, leveraging Livewire’s reactivity model. The package extends Filament’s existing concerns (InteractsWithResourceLock, HasResourceLocks) without requiring architectural overhauls.
• Modular Design: Locking logic (heartbeat/broadcast), storage (database/Redis), and audit features are decoupled via configuration. This aligns with Laravel’s service container and Filament’s plugin system.
• SPA-Friendly: Built for Filament’s SPA navigation (wire:navigate), with broadcast mode using Laravel Echo for near-instant updates. Avoids full-page reloads, critical for modern admin UIs.
• Audit as First-Class Citizen: Locking and auditing are tightly coupled but optional. Audit history shares the same lock cycle ID, enabling rollback tied to specific editing sessions.

Integration Feasibility

• Low Friction for Filament v5: Requires 3 lines of code to enable locking on a resource (model trait + page concern + table column). No middleware or route changes unless using broadcast mode.
• Broadcast Mode Dependency: If using broadcast driver, requires:
  • Laravel Echo setup (Reverb/Pusher/Ably).
  • Frontend window.Echo configuration.
  • Signed route for soft release (already registered by the package).
• Database Schema: Adds two tables (resource_locks, resource_lock_audits) via migrations. Schema is opinionated but extensible (e.g., custom user_display_column).
• Frontend Assets: Publishes JavaScript for Echo events. Minimal risk if using heartbeat mode.

Technical Risk

Key Questions for TPM

1. Collaboration Workflows:
   • Are users editing records simultaneously (requiring strict locks) or sequentially (optimistic locking sufficient)?
   • Should lock handoff (save_and_unlock) be automatic or manual (requires permission)?
2. Real-Time Requirements:
   • Is broadcast mode justified (Echo setup cost) or is heartbeat (polling) acceptable?
   • What’s the maximum tolerable lock latency (e.g., 10s vs. 1s)?
3. Audit Compliance:
   • Are rollback capabilities critical (e.g., financial corrections) or optional?
   • Should audit history be permanent or time-bound (e.g., 30-day retention)?
4. Performance:
   • What’s the expected lock contention rate (e.g., 100 locks/sec)? Redis may be needed.
   • How will large forms (100+ fields) impact audit diff rendering?
5. Customization:
   • Are there unsupported Filament fields (e.g., custom components) requiring HasAuditDiffPreview?
   • Should lock UI/UX (e.g., notifications, timeout behavior) be customized?

Integration Approach

Stack Fit

• Laravel: Compatible with Laravel 12/13. Uses Eloquent models, Livewire, and Laravel Echo.
• Filament v5: Native support for EditRecord pages. No panel/plugin registration needed.
• Frontend: Works with Filament’s Alpine.js/Livewire setup. Broadcast mode requires Echo.
• Storage: Supports database (default) or Redis for locks/audits.
• Broadcast: Requires Laravel Echo (Reverb/Pusher/Ably) + private channels.

Migration Path

Compatibility

• Filament v5 Only: Hard dependency. No backward compatibility with v4/v3.
• Livewire 3.x: Assumed (Filament v5 uses it).
• Eloquent Models: Requires HasResourceLocks trait on models.
• Custom Fields: Audit diffs require HasAuditDiffPreview for unsupported fields.
• Broadcast Providers: Tested with Reverb/Pusher. Ably may need config tweaks.

Sequencing

1. Start with Heartbeat Mode:
   • Validate core locking behavior (no Echo dependency).
   • Test lock acquisition/release, UI feedback, and handoff.
2. Add Broadcast Later:
   • Only if real-time updates are critical (e.g., high-contention workflows).
   • Requires Echo setup and channel prefix tuning.
3. Audit as Final Step:
   • Enable only after locking is stable.
   • Test rollback and diff rendering with complex forms.

Operational Impact

Maintenance

• Dependencies:
  • Laravel Echo (if using broadcast).
  • Redis (if using Redis storage).
  • Filament v5 (strict version pinning recommended).
• Updates:
  • Monitor for Filament v5 breaking changes.
  • Audit diff logic may need updates for new Filament field types.
• Logs/Monitoring:
  • Track filament-resource-lock.* logs for lock timeouts or stale releases.
  • Monitor resource_locks table for orphaned locks (e.g., updated_at > now() - interval 1 hour).

Support

• Common Issues:
  • Stale Locks: Increase stale_soft_release_ignore_seconds or ttl_seconds.
  • Broken Audits: Ensure save() calls syncResourceAuditBeforeSave()/AfterSave().
  • Broadcast Failures: Verify Echo channels and APP_URL for signed routes.
• User Training:
  • Explain lock UI cues (e.g., disabled form, "User X is editing" banner).
  • Document handoff workflow (save_and_unlock vs. ask_to_unblock).
• Fallbacks:
  • Disable broadcast mode if Echo is unreliable.
  • Provide admin tool to manually release stuck locks (e.g., DB::table('resource_locks')->where(...)->delete()).

Scaling

• Lock Contention:
  • Database Driver: May hit SELECT FOR UPDATE contention under high load. Consider Redis.
  • Redis Driver: Scales better for high lock volume (e.g., >100 locks/sec).
• Audit Storage:
  • Prune old entries via audit.max_entries_per_resource.
  • Add indexes on lock_cycle_id and created_at for large audit tables.
• Broadcast Scaling:
  • Echo channels should scale with your broadcast driver (e.g., Reverb auto-scales).

Failure Modes