Filament Spotlight Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require pxlrbt/filament-spotlight
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Pxlrbt\FilamentSpotlight\FilamentSpotlightServiceProvider"
   

2. Basic Setup Register the Spotlight widget in your Filament admin panel’s app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->widgets([
               \Pxlrbt\FilamentSpotlight\Widgets\Spotlight::class,
           ]);
   }
   

3. First Use Case Use Spotlight to highlight key admin actions (e.g., "Create Post," "View Users") by defining them in the config:

   'spotlight' => [
       'actions' => [
           'posts.create' => [
               'label' => 'Create New Post',
               'icon' => 'heroicon-o-pencil-square',
               'url' => route('admin.posts.create'),
           ],
       ],
   ],
   

Implementation Patterns

Core Workflows

1. Dynamic Action Registration Register actions programmatically in a service provider or widget:

   Spotlight::registerAction('users.export', [
       'label' => 'Export Users',
       'icon' => 'heroicon-o-arrow-down-tray',
       'url' => route('admin.users.export'),
       'can' => fn () => auth()->user()->can('export-users'),
   ]);
   

2. Conditional Visibility Use closures to control action visibility:

   'spotlight' => [
       'actions' => [
           'reports.generate' => [
               'label' => 'Generate Report',
               'visible' => fn () => now()->day === 1, // Only show on 1st of the month
           ],
       ],
   ],
   

3. Custom Styling Override Blade templates (e.g., resources/views/vendor/filament-spotlight/spotlight.blade.php) to modify appearance.

4. Integration with Filament Resources Link Spotlight actions to resource actions:

   Spotlight::registerAction('posts.publish', [
       'label' => 'Publish Post',
       'url' => fn (Post $post) => route('admin.posts.edit', $post),
       'can' => fn () => auth()->user()->can('publish-posts'),
   ]);
   

Advanced Patterns

• Multi-Tenancy Support Dynamically filter actions per tenant:

  'spotlight' => [
      'actions' => [
          'tenants.switch' => [
              'label' => 'Switch Tenant',
              'url' => route('admin.tenants.switch', ['tenant' => auth()->user()->tenant_id]),
          ],
      ],
  ],
  

• Search Optimization Preload action data in a widget’s getData() method to avoid N+1 queries.

Gotchas and Tips

Common Pitfalls

1. Action URL Resolution

   • Issue: Hardcoded URLs may break if routes change.
   • Fix: Use named routes (route('admin.posts.create')) or dynamic closures:

     'url' => fn () => route('admin.posts.create', ['user_id' => auth()->id()]),
     

2. Permission Caching

   • Issue: can() closures may not update in real-time.
   • Fix: Clear Filament’s cache (php artisan filament:cache-reset) or use event listeners to refresh permissions.

3. Template Overrides

   • Issue: Custom Blade templates may not inherit parent styles.
   • Fix: Extend the base template:

     @extends('filament-spotlight::spotlight')
     @section('actions')
         @parent
         <x-filament-spotlight::action ... />
     @endsection
     

4. Performance

   • Issue: Too many actions slow down the widget.
   • Fix: Lazy-load actions or paginate them in the config:

     'spotlight' => [
         'actions_per_page' => 5,
     ],
     

Debugging Tips

• Log Actions: Enable debug mode in config to log registered actions:

  'debug' => env('APP_DEBUG', false),
  

• Check Filament Events: Listen for Filament\Contracts\Plugin events to debug widget initialization:

  Event::listen(Filament\Contracts\Plugin::class, fn ($plugin) => logger()->info($plugin->getId()));
  

Extension Points

1. Custom Action Types Extend the Pxlrbt\FilamentSpotlight\Contracts\Action interface to add interactive elements (e.g., modals, forms).

2. Database-Backed Actions Store actions in a spotlight_actions table and hydrate them dynamically:

   Spotlight::registerActions(SpotlightAction::query()->where('user_id', auth()->id())->get());
   

3. Localization Support multi-language labels:

   'label' => fn () => __("filament-spotlight::actions.posts.create"),