Filament Plugin Schedule Monitor Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies Run these commands in sequence:

   composer require spatie/laravel-schedule-monitor
   php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-migrations"
   php artisan migrate
   composer require mvenghaus/filament-plugin-schedule-monitor:"^3.0"
   

2. Register the Plugin Add the plugin to your AdminPanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(\Mvenghaus\FilamentScheduleMonitor\FilamentPlugin::make());
   }
   

3. First Use Case Visit your Filament admin panel. The plugin adds a "Schedule Monitor" widget to the dashboard by default, showing:

   • Last run status of scheduled commands.
   • Run duration and exceptions.
   • Quick visual indicators for failures.

Implementation Patterns

Core Workflows

1. Dashboard Integration

   • The plugin auto-registers a widget in Filament’s dashboard. To customize its position:

     FilamentPlugin::make()
         ->widgets([
             \Mvenghaus\FilamentScheduleMonitor\Widgets\ScheduleMonitorWidget::class,
         ])
         ->sort(10); // Adjust priority
     

2. Resource Integration (Optional)

   • For deeper inspection, create a Filament resource to list all scheduled commands:

     use Mvenghaus\FilamentScheduleMonitor\Resources\ScheduleMonitorResource;
     
     FilamentPlugin::make()
         ->resources([
             ScheduleMonitorResource::class,
         ]);
     

   • Access via Resources > Schedule Monitor in the Filament sidebar.

3. Customizing Data Display

   • Override the widget’s query or table columns by extending the widget class:

     class CustomScheduleMonitorWidget extends ScheduleMonitorWidget
     {
         protected function getTableQuery(): Builder
         {
             return parent::getTableQuery()->where('command', 'like', '%backup%');
         }
     }
     

   • Register it in the plugin config:

     FilamentPlugin::make()
         ->widgets([
             CustomScheduleMonitorWidget::class,
         ]);
     

4. Conditional Visibility

   • Show/hide the widget based on environment or user roles:

     FilamentPlugin::make()
         ->widgets([
             ScheduleMonitorWidget::class,
         ])
         ->visible(fn (User $user) => $user->isAdmin());
     

Integration Tips

• Leverage Spatie’s Features The plugin surfaces Spatie’s laravel-schedule-monitor data. Use Spatie’s documentation to:

  • Configure schedule:run in app/Console/Kernel.php.
  • Set up custom command logging or notifications.

• Combine with Filament Actions Add buttons to trigger commands manually from the resource:

  ScheduleMonitorResource::class,
  use Filament\Resources\Actions\Action;
  
  public static function getActions(): array
  {
      return [
          Action::make('Run Now')
              ->url(fn ($record) => route('schedule.run', $record->command))
              ->openUrlInNewTab(),
      ];
  }
  

• Notifications for Failures Extend the plugin to send alerts (e.g., Slack, Email) when jobs fail:

  // In a Service Provider
  ScheduleMonitor::failed(function (FailedJob $failedJob) {
      Notification::route('mail', 'admin@example.com')
                  ->notify(new ScheduleFailed($failedJob));
  });
  

Gotchas and Tips

Pitfalls

1. Missing Migrations

   • Forgetting to run php artisan migrate after installing spatie/laravel-schedule-monitor will break the plugin. Always run:

     php artisan migrate
     

2. Caching Issues

   • Filament’s dashboard caches widgets. Clear the cache after changes:

     php artisan filament:cache-reset
     

3. Permission Denied

   • The plugin requires access to Spatie’s schedule_monitor tables. Ensure your Filament user has database permissions.

4. Command Not Logging

   • If commands don’t appear in the monitor, verify:
     • The command is registered in app/Console/Kernel.php under $schedule.
     • The schedule:run command is executed (e.g., via cron or manually).

Debugging

• Check Logs Enable debug mode for Spatie’s monitor:

  // config/schedule-monitor.php
  'debug' => env('SCHEDULE_MONITOR_DEBUG', false),
  

  Logs appear in storage/logs/laravel.log.

• Verify Database Records Inspect the schedule_monitor_runs table directly:

  SELECT * FROM schedule_monitor_runs ORDER BY created_at DESC LIMIT 10;
  

• Test Locally Manually trigger a scheduled command to populate data:

  php artisan schedule:run
  

Tips

1. Custom Styling Override the widget’s Blade view (resources/views/widgets/schedule-monitor.blade.php) or use Filament’s CSS variables:

   .filament-schedule-monitor {
       --fail-color: #ef4444;
       --success-color: #10b981;
   }
   

2. Performance For large schedules, paginate the resource:

   ScheduleMonitorResource::class,
   use Filament\Resources\Table;
   
   public static function getTable(): Table
   {
       return Table::make(...)
           ->paginate(20);
   }
   

3. Environment-Specific Config Disable the plugin in non-production environments:

   FilamentPlugin::make()
       ->visible(fn () => app()->environment('production')),
   

4. Extend Functionality Add custom columns to the resource table:

   Table::make(...)
       ->columns([
           TextColumn::make('command')
               ->searchable(),
           TextColumn::make('duration')
               ->formatStateUsing(fn ($state) => $state ? round($state, 2) . 's' : 'N/A'),
           // Add more columns as needed
       ]),
   

5. Localization Translate widget labels by publishing the language file:

   php artisan vendor:publish --tag="filament-schedule-monitor-lang"
   

   Then edit resources/lang/en/filament-schedule-monitor.php.