Filament Modal Relation Managers Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require guava/filament-modal-relation-managers
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Guava\FilamentModalRelationManagers\FilamentModalRelationManagersServiceProvider"
   

2. First Use Case Embed a relation manager in a modal for a Post model with a comments relation:

   use Guava\FilamentModalRelationManagers\Actions\ModalRelationManager;
   
   public static function getModalActions(): array
   {
       return [
           ModalRelationManager::make('comments')
               ->modalHeading('Manage Comments')
               ->modalSubheading('Edit or add comments for this post')
               ->relationName('comments'),
       ];
   }
   

3. Where to Look First

   • README for version compatibility and basic usage.
   • Actions API for available methods.
   • Examples in the docs for common use cases.

Implementation Patterns

Common Workflows

1. Basic Modal Integration Attach a relation manager to a Filament resource action:

   ModalRelationManager::make('author')
       ->relationName('author')
       ->modalHeading('Edit Author')
       ->modalDescription('Update the author details for this post.')
   

2. Dynamic Modal Content Use closures for dynamic modal configuration:

   ModalRelationManager::make('tags')
       ->relationName('tags')
       ->modalHeading(fn ($record) => "Tags for {$record->title}")
       ->modalWidth('50%')
   

3. Nested Relations Handle nested relations (e.g., Post → Categories → Subcategories):

   ModalRelationManager::make('categories')
       ->relationName('categories')
       ->modalRelationManager(
           ModalRelationManager::make('subcategories')
               ->relationName('subcategories')
       )
   

4. Custom Relation Managers Extend existing relation managers (e.g., Table, Select, RelationManager):

   ModalRelationManager::make('images')
       ->relationName('images')
       ->modalRelationManager(
           Filament\Tables\Table::make('images')
               ->columns([...])
               ->actions([...])
       )
   

5. Modal Events Listen to modal events for custom logic:

   ModalRelationManager::make('reviews')
       ->relationName('reviews')
       ->modalOpened(fn ($modal) => Log::info('Modal opened for reviews'))
       ->modalClosed(fn ($modal) => Log::info('Modal closed for reviews'))
   

Integration Tips

• Filament Resource Actions: Place the action in getActions() or getTableActions().
• Modal Styling: Use modalWidth(), modalMaxWidth(), or modalHeight() for responsive layouts.
• Relation Filtering: Pass a closure to query() to filter relations dynamically:

  ModalRelationManager::make('users')
      ->relationName('users')
      ->query(fn ($query) => $query->where('active', true))
  

• Form Integration: Combine with Filament\Forms\Components for custom forms inside modals.

Gotchas and Tips

Pitfalls

1. Relation Name Mismatch

   • Issue: The relationName must match the actual relation defined in your model.
   • Fix: Verify the relation exists in the model:

     public function comments()
     {
         return $this->hasMany(Comment::class);
     }
     

2. Modal Not Triggering

   • Issue: The action might not appear due to missing permissions or incorrect placement.
   • Fix: Ensure the action is added to getActions() or getTableActions() and check Filament’s permission policies.

3. Nested Modal Conflicts

   • Issue: Nested modals may not render correctly if not properly configured.
   • Fix: Use modalRelationManager() for nested relations and avoid circular references.

4. CSRF Token Errors

   • Issue: Modal submissions may fail with CSRF errors if the modal is not properly bound to the parent resource.
   • Fix: Ensure the modal is triggered from a Filament resource page (not a standalone route).

Debugging

• Check Logs: Enable debug mode (APP_DEBUG=true) and inspect Filament logs for relation manager errors.
• Inspect Blade: Use browser dev tools to verify the modal HTML structure and ensure relation managers are rendered.
• Test Relations: Manually test relations in Tinker or a controller to confirm they work outside the modal:

  php artisan tinker
  >>> $post = Post::first();
  >>> $post->comments
  

Configuration Quirks

1. Default Modal Width

   • The package defaults to modalWidth('60%'). Override with:

     ModalRelationManager::make('relation')->modalWidth('80%');
     

2. Modal Footer Actions

   • By default, the modal includes a "Save" button. Disable with:

     ModalRelationManager::make('relation')->disableSaveButton();
     

3. Relation Manager Type

   • The package supports Table, Select, and RelationManager out of the box. For custom types, extend the base class:

     use Guava\FilamentModalRelationManagers\Actions\Concerns\HasModalRelationManager;
     
     class CustomModalRelationManager extends ModalRelationManager
     {
         use HasModalRelationManager;
     
         public static function make(string $name): static
         {
             return tap(new static(), fn ($action) => $action->name($name));
         }
     }
     

Extension Points

1. Custom Modal Content Override the default modal content using modalContent():

   ModalRelationManager::make('relation')
       ->modalContent(fn ($record) => view('custom.modal', ['record' => $record]))
   

2. Modal Events Extend functionality with events:

   ModalRelationManager::make('relation')
       ->modalOpened(fn ($modal) => event(new ModalOpened($modal)))
       ->modalClosed(fn ($modal) => event(new ModalClosed($modal)));
   

3. Relation Manager Customization Pass a custom relation manager instance:

   ModalRelationManager::make('relation')
       ->modalRelationManager(
           Filament\Tables\Table::make('custom-table')
               ->columns([...])
               ->actions([...])
       )