Filament Resource Lock Laravel Package

Technical Evaluation

Architecture Fit

• Filament v5 Native Integration: Designed specifically for Filament’s EditRecord pages, leveraging Livewire’s reactivity and Filament’s component ecosystem. The package extends Filament’s existing patterns (e.g., Concerns, Resources/Columns) without forcing architectural changes.
• Modular Design: Core locking logic is decoupled from audit history, allowing selective adoption (e.g., use locking without auditing or vice versa). This aligns with the principle of progressive enhancement.
• Event-Driven Extensibility: Supports both polling (heartbeat) and broadcast (Laravel Echo) modes, enabling flexibility based on infrastructure (e.g., Redis vs. database-backed locks). Broadcast mode integrates with Laravel’s event system, reducing client-side polling overhead.
• Audit as a First-Class Citizen: Audit history is built into the lock lifecycle, with diff rendering tailored to Filament field types (e.g., RichEditor, Select). This reduces the need for third-party diff libraries or custom implementations.

Integration Feasibility

• Low Friction for Filament v5: Requires only 3 steps to enable locking on a resource:
  1. Add HasResourceLocks to the model.
  2. Add InteractsWithResourceLock to the EditRecord page.
  3. Include the ResourceLockColumn in the list table.
• Minimal Backend Changes: No need to modify core Filament or Laravel routing; the package registers its own signed route (filament-resource-lock.release) for soft unlocks.
• Frontend Alignment: Works seamlessly with Filament’s SPA navigation (wire:navigate) and Livewire’s reactivity. Broadcast mode requires minimal Echo setup (e.g., publishing JS assets and configuring channels).
• Database Schema: Adds two tables (resource_locks and optionally resource_lock_audits), which can be scoped to specific models or shared globally. Migrations are published but not run by default, giving control over schema changes.

Technical Risk

• Broadcast Dependency: Broadcast mode requires Laravel Echo + a queue driver (e.g., Redis, Reverb). Teams using polling (heartbeat) avoid this dependency but trade off latency (~10s refresh vs. real-time).
• Audit Storage Overhead: Audit history stores snapshots of form state, which can grow large for high-frequency edits. The package includes pruning logic (max_entries_per_resource), but misconfiguration risks bloating the database.
• Custom Field Support: Audit diffs rely on Filament’s built-in field types. Custom fields require manual implementation of HasAuditDiffPreview, adding maintenance overhead for non-standard UI components.
• Session Management: Soft release routes depend on signed URLs and APP_URL correctness. Misconfigured URLs may break unlock flows, especially in multi-tenant or dynamic-domain environments.
• Livewire Compatibility: Potential edge cases with multiple tabs/windows opening the same resource (e.g., race conditions during lock acquisition). The package addresses this in v2.1.2, but custom Livewire logic could introduce regressions.
• Permission System: Relies on Laravel’s auth()->user()->can() for actions like save_and_unlock. Teams using custom permission systems (e.g., Gates, Policies) may need to adapt or extend the package.

Key Questions

1. Collaboration Workflow Needs:
   • Is real-time feedback (broadcast) critical, or is polling sufficient?
   • Do users need handoff mechanisms (e.g., "request unlock"), or is blocking alone adequate?
2. Audit Requirements:
   • Is audit history mandatory, or is locking alone sufficient for data integrity?
   • What is the expected retention period for audit snapshots? Will max_entries_per_resource need adjustment?
3. Infrastructure Constraints:
   • Is Laravel Echo already configured, or will broadcast mode require additional setup (e.g., Pusher/Reverb)?
   • What is the expected scale of concurrent locks? Redis may be preferable for high-throughput scenarios.
4. Customization Needs:
   • Are there non-standard Filament fields that require audit diff support? If so, will the team maintain custom HasAuditDiffPreview implementations?
   • Does the application override save() in EditRecord pages? If yes, audit functionality may need explicit reintegration.
5. Deployment Risks:
   • How will the package be versioned in a monorepo or CI/CD pipeline? (Note: composer dump-autoload may be needed after local code changes.)
   • Are there multi-region deployments where signed URL validation (for soft release) could fail due to APP_URL mismatches?

Integration Approach

Stack Fit

• Filament v5: Optimized for Filament’s component model, with zero conflicts with core Filament features (e.g., forms, tables, widgets).
• Laravel 12/13: Leverages Laravel’s broadcasting, Livewire, and Eloquent features natively. No polyfills or compatibility layers required.
• Livewire: Built on Livewire’s reactivity model, ensuring smooth integration with Filament’s SPA-like navigation.
• Database/Redis: Storage drivers are interchangeable, allowing teams to choose based on performance or cost (e.g., Redis for high concurrency, database for simplicity).
• JavaScript: Minimal frontend footprint; only requires Echo setup for broadcast mode. Polling mode works with zero JS changes.

Migration Path

1. Assessment Phase:
   • Audit existing EditRecord pages to identify candidates for locking (e.g., high-conflict resources like Users, Orders).
   • Evaluate broadcast infrastructure (if desired) by testing Laravel Echo with a non-critical resource.
2. Pilot Implementation:
   • Start with polling mode (heartbeat) on a single resource to validate core locking behavior.
   • Gradually enable audit history if needed, testing diff rendering and rollback flows.
3. Broadcast Rollout:
   • Configure Laravel Echo (e.g., Reverb) and update config/filament-resource-lock.php to use broadcast mode.
   • Monitor lock contention and latency improvements in production-like staging.
4. Full Adoption:
   • Roll out locking to additional resources, prioritizing those with the highest collision risk.
   • Enable soft release for critical resources to handle tab closure gracefully.

Compatibility

• Filament Plugins: No known conflicts with other Filament plugins, as the package operates at the resource/page level.
• Custom Livewire Components: Locking logic is isolated to EditRecord pages. Custom Livewire components outside Filament are unaffected.
• Model Events: Audit snapshots are captured via save() hooks, which may conflict with existing model observers or listeners. The package provides explicit guidance for overriding save() while preserving audit functionality.
• Localization: Supports English and Russian out-of-the-box. Additional locales can be added via standard Laravel translation mechanisms.

Sequencing

1. Prerequisites:
   • Ensure Laravel 12/13 and Filament v5 are up-to-date.
   • For broadcast mode: Set up Laravel Echo (e.g., Reverb) and configure BROADCAST_DRIVER in .env.
2. Installation:

   composer require androsamp/filament-resource-lock
   php artisan filament-resource-lock:install
   php artisan migrate
   

   • Publish only necessary resources (config, migrations, assets) to avoid overwriting customizations.
3. Configuration:
   • Update config/filament-resource-lock.php for TTL, storage driver, and permissions.
   • Test both heartbeat and broadcast modes in staging.
4. Resource Integration:
   • Add HasResourceLocks to models and InteractsWithResourceLock to EditRecord pages.
   • Include ResourceLockColumn in list tables for visibility.
5. Audit Setup (Optional):
   • Add HasResourceAudit to pages requiring history.
   • Override save() if needed (see README).
6. Testing:
   • Validate lock acquisition/release in single-user and multi-user scenarios.
   • Test audit diffs for custom fields and rollback functionality.
   • Simulate edge cases (e.g., rapid tab switching, network interruptions).

Operational Impact

Maintenance

• Package Updates: The package is actively maintained (last release: 2026-06-05), with a clear changelog. Breaking changes are documented (e.g., v2.0.0 added auditing).
• Customization Overhead:
  • Low: Core locking requires no maintenance after initial setup.
  • Moderate: Audit history may need tuning (e.g., max_entries_per_resource) or custom diff support for non-standard fields.
• Dependency Risks:
  • Tied to Filament v5 and Laravel 12/13. Upgrading Filament may require package updates.
  • Broadcast mode depends on Echo infrastructure (e.g., Reverb, Pusher). Outages here could disrupt locking.

Support

• **