Filament Command Runner Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require binarybuilds/filament-command-runner
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="BinaryBuilds\FilamentCommandRunner\FilamentCommandRunnerServiceProvider" --tag="filament-command-runner-config"
   php artisan vendor:publish --provider="BinaryBuilds\FilamentCommandRunner\FilamentCommandRunnerServiceProvider" --tag="filament-command-runner-migrations"
   php artisan migrate
   

2. Register the Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \BinaryBuilds\FilamentCommandRunner\FilamentCommandRunnerPlugin::make(),
           ]);
   }
   

3. First Use Case: Define a command in config/filament-command-runner.php:

   'commands' => [
       'optimize:clear' => [
           'label' => 'Optimize:Clear',
           'description' => 'Clear Laravel cache and optimize',
           'command' => 'optimize:clear',
           'is_artisan' => true,
           'is_hidden' => false,
       ],
   ],
   

   Access via Filament Admin Panel > Command Runner tab.

Implementation Patterns

Workflows

1. Command Definition:

   • Artisan Commands: Use is_artisan: true and specify the command name.
   • Shell Commands: Use is_artisan: false and provide the full shell command (e.g., command: 'php artisan queue:work --once').
   • Dynamic Commands: Use command closure for runtime-generated commands:

     'command' => function () {
         return 'queue:work --once --queue=' . request('queue');
     },
     

2. Grouping Commands: Organize commands into logical groups using the group key:

   'commands' => [
       'cache' => [
           'group' => 'Cache Management',
           'commands' => [
               'optimize:clear',
               'cache:clear',
           ],
       ],
   ],
   

3. Permissions & Visibility: Control access via Filament’s built-in policies or custom gates:

   'commands' => [
       'migrate' => [
           'is_hidden' => true, // Hide by default
           'can_run' => function () {
               return auth()->user()->can('run-migrations');
           },
       ],
   ],
   

4. Output Handling:

   • Real-time Logs: Users see live output via WebSocket (if configured).
   • Stored Output: Logs persist in the database for later review.

5. Integration with Filament Resources/Pages: Embed the command runner in custom pages:

   use BinaryBuilds\FilamentCommandRunner\Widgets\CommandRunnerWidget;
   
   public static function getWidgets(): array
   {
       return [
           CommandRunnerWidget::make()
               ->commands(['optimize:clear', 'queue:work']),
       ];
   }
   

Gotchas and Tips

Pitfalls

1. Command Timeouts:

   • Long-running commands may hit PHP’s max_execution_time. Configure via config/filament-command-runner.php:

     'timeout' => 3600, // 1 hour in seconds
     

   • For shell commands, ensure the process is properly detached (e.g., nohup or disown).

2. Database Bloat:

   • Command logs accumulate in command_runs table. Implement cleanup via:

     'prune_old_logs' => true, // Enable in config
     'log_retention_days' => 30, // Keep logs for 30 days
     

3. Permission Issues:

   • Shell commands may fail if the web server user lacks permissions. Use sudo cautiously or adjust file permissions:

     chmod -R 775 storage/
     

4. WebSocket Dependencies:

   • Real-time updates require Laravel Echo/Pusher. If missing, logs update only on page refresh.

Debugging

1. Command Failures:

   • Check storage/logs/laravel.log for execution errors.
   • Verify the command works manually in the terminal before adding it to the config.

2. Queue Workers:

   • Ensure the queue worker is running (php artisan queue:work) for background execution:

     'uses_queue' => true, // Enable in config
     

3. Output Truncation:

   • Adjust max_output_length in config to handle large outputs:

     'max_output_length' => 10000, // 10KB
     

Extension Points

1. Custom Command Classes: Extend \BinaryBuilds\FilamentCommandRunner\Commands\Command for reusable logic:

   namespace App\Commands;
   
   use BinaryBuilds\FilamentCommandRunner\Commands\Command;
   
   class CustomCommand extends Command
   {
       public function getCommand(): string
       {
           return 'custom:command --param=' . $this->param;
       }
   }
   

2. Event Listeners: Listen for command events (e.g., CommandStarted, CommandCompleted):

   use BinaryBuilds\FilamentCommandRunner\Events\CommandCompleted;
   
   CommandCompleted::listen(function (CommandCompleted $event) {
       Log::info('Command finished: ' . $event->command);
   });
   

3. API Access: Expose commands via a custom API endpoint for non-admin users:

   Route::post('/api/run-command', function () {
       return \BinaryBuilds\FilamentCommandRunner\Facades\CommandRunner::run(
           request('command'),
           request('user') // Optional: associate with a user
       );
   });
   

4. Theming: Customize the UI via Filament’s theming system:

   FilamentCommandRunnerPlugin::make()
       ->colors([
           'success' => '#10B981',
           'danger' => '#EF4444',
       ]),