Filament Restore Or Create Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Ideal for Laravel applications using FilamentPHP (admin panel) where soft-deleted records (via Laravel’s SoftDeletes) may unintentionally be recreated as duplicates. The package bridges the gap between data integrity and UX by preventing accidental duplicates via a restore-first approach.
• Laravel Ecosystem Fit: Leverages native Laravel features (SoftDeletes, Eloquent) and Filament’s form/modal system, ensuring minimal architectural disruption. Works seamlessly with existing Laravel apps using Filament for admin interfaces.
• Customization Hooks: Offers extensibility via customizable detection logic (e.g., fuzzy matching, field-specific rules) and modal UI, making it adaptable to domain-specific requirements (e.g., e-commerce SKUs, user profiles).

Integration Feasibility

• Low-Coupling Design: Package injects behavior into Filament forms without modifying core business logic or existing models. Uses Laravel service providers and Filament’s plugin system for clean integration.
• Dependency Requirements:
  • Mandatory: Laravel 10+, FilamentPHP 3.x, SoftDeletes trait.
  • Optional: Custom matchers (e.g., Laravel Scout for full-text search) if default detection (exact field matches) is insufficient.
• Database Impact: No schema changes required; relies on existing soft-deleted records. May require indexing on frequently matched fields (e.g., email, sku) for performance.

Technical Risk

• False Positives/Negatives: Default detection (exact field matches) may not cover all edge cases (e.g., partial matches, typos). Custom matchers add complexity but mitigate risk.
• Performance: Scanning soft-deleted records on every create operation could impact large datasets. Mitigation: Limit scope (e.g., recently_deleted()) or add caching.
• Filament Version Lock: Tied to Filament 3.x; potential upgrade risks if Filament evolves its form/modal APIs.
• Testing Gaps: Limited test coverage for edge cases (e.g., concurrent restores, nested relationships). Requires custom validation in production.

Key Questions

1. Detection Logic:
   • Are exact field matches sufficient, or do we need fuzzy matching (e.g., Levenshtein distance for names)?
   • Should we integrate with Laravel Scout or another search backend for scalability?
2. User Experience:
   • How should the modal handle cases where multiple similar records exist? (Prioritization? Bulk restore?)
   • Should restored records trigger additional workflows (e.g., notifications, audit logs)?
3. Performance:
   • What’s the expected volume of soft-deleted records? Are queries optimized (e.g., whereNull('deleted_at') scope)?
4. Fallback Behavior:
   • If no match is found, should the package silently create the record, or log a warning?
5. Localization:
   • Does the modal UI need translation for non-English Filament instances?

Integration Approach

Stack Fit

• Primary Stack: Laravel 10+ with FilamentPHP 3.x (admin panel). Compatible with:
  • Eloquent models using SoftDeletes.
  • Filament forms/resources (e.g., Filament\Forms\Components\TextInput).
  • Custom validation rules or Laravel Policies for pre-create logic.
• Secondary Stack:
  • Search: Laravel Scout or Algolia for fuzzy matching (if default logic is insufficient).
  • Notifications: Laravel Echo/Pusher for real-time restore confirmations.
  • Audit: Laravel Audit or custom logs for tracking restores.

Migration Path

1. Preparation:
   • Ensure models use SoftDeletes and Filament forms are up-to-date.
   • Identify critical fields for duplicate detection (e.g., email, reference_number).
2. Installation:

   composer require martinpetricko/filament-restore-or-create
   

   • Publish config (if needed) to customize detection rules or modal UI.
3. Integration:
   • Register the plugin in AppServiceProvider:

     Filament::registerPlugin(RestoreOrCreatePlugin::make());
     

   • Apply to specific resources/forms via:

     use MartinPetricko\FilamentRestoreOrCreate\Concerns\InteractsWithRestoreOrCreate;
     
     class MyResource extends Resource {
         use InteractsWithRestoreOrCreate;
     }
     

4. Testing:
   • Unit test custom matchers and edge cases (e.g., empty soft-deletes table).
   • UI test the modal flow in Filament.

Compatibility

• Backward Compatibility: No breaking changes expected for Filament 3.x. Future-proofing requires monitoring Filament’s form API changes.
• Conflict Risks:
  • Other Filament plugins modifying form submission logic (e.g., custom validation).
  • Model observers or accessors that alter field values before detection.
• Fallback: Graceful degradation if the package fails (e.g., log error, proceed with create).

Sequencing

1. Phase 1: Pilot on non-critical resources (e.g., low-volume admin forms).
2. Phase 2: Roll out to high-risk resources (e.g., orders, users) with custom matchers.
3. Phase 3: Optimize performance (e.g., add indexes, cache soft-deleted queries).
4. Phase 4: Extend with custom UI (e.g., restore history table in Filament).

Operational Impact

Maintenance

• Dependency Updates: Monitor Filament and Laravel minor versions for compatibility. Package updates likely quarterly (based on last release date).
• Custom Logic: Highly customizable matchers/modals may require maintenance if business rules change (e.g., new duplicate detection criteria).
• Documentation: Limited but clear README. May need internal docs for custom configurations.

Support

• Troubleshooting:
  • Common issues: False positives, performance bottlenecks, modal styling conflicts.
  • Debugging tools: Laravel logs, Filament’s filament:debug command.
• Community: Small but active GitHub repo (11 stars, recent releases). Issues resolved within days.
• SLA: No official support; rely on community or vendor (MartinPetricko) for critical bugs.

Scaling

• Performance:
  • Small/Medium: Negligible impact with default settings.
  • Large: Add database indexes on matched fields (e.g., email), limit soft-deleted scope (e.g., last 6 months), or use Scout.
  • Caching: Cache soft-deleted queries if detection runs frequently (e.g., Redis).
• Concurrency: Thread-safe for single-record operations. Concurrent restores may require optimistic locking (version column).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time: 1–2 hours to integrate basic functionality.
  • Skills Needed: Familiarity with Laravel Eloquent, Filament forms, and soft deletes.
  • Training: Review package’s README and Filament’s plugin system docs.
• Business Stakeholder Impact:
  • Benefits: Reduces duplicate data entry, improves data integrity.
  • Risks: Initial confusion around "restore vs. create" modal; require UAT for edge cases.
• Rollout Strategy:
  • Pilot: Test with a small team on a non-production Filament resource.
  • Feedback Loop: Gather input on false positives/UX before full rollout.
  • Training: Document modal workflow for end users (e.g., "How to handle restore prompts").