Filament Artisan Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tomatophp/filament-artisan
   

   Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(\TomatoPHP\FilamentArtisan\FilamentArtisanPlugin::make())
   

2. First Use Case:

   • Navigate to /filament/artisan (or your Filament panel URL with /artisan appended).
   • Select an Artisan command (e.g., migrate, optimize:clear, filament:install).
   • Run it directly from the UI with optional arguments (if supported).

Where to Look First

• Configuration: Check config/filament-artisan.php for environment restrictions (default: local only).
• Commands List: The /artisan page lists all available commands with their signatures.
• Output: Results appear in a dedicated output panel with logs and success/error messages.

Implementation Patterns

Common Workflows

1. Running Standard Commands:

   • Use the dropdown to select a command (e.g., db:wipe, filament:make).
   • Fill in required arguments (e.g., --force for destructive commands).
   • Click "Run" and monitor output in real-time.

2. Custom Command Integration:

   • Extend the plugin by publishing its config:

     php artisan vendor:publish --provider="TomatoPHP\FilamentArtisan\FilamentArtisanServiceProvider"
     

   • Add custom commands to config/filament-artisan.php under commands:

     'commands' => [
         'your:custom-command' => [
             'description' => 'Run a custom task',
             'arguments' => [
                 ['name' => 'param', 'description' => 'Input parameter'],
             ],
         ],
     ],
     

   • Register the command in app/Console/Kernel.php:

     protected $commands = [
         \YourNamespace\Commands\YourCustomCommand::class,
     ];
     

3. Environment-Specific Access:

   • Modify config/filament-artisan.php to allow commands in non-local environments:

     'environments' => ['local', 'staging'], // Add 'production' cautiously!
     

4. Bulk Operations:

   • Chain commands (if supported) by separating them with && in the input field (e.g., migrate && optimize).

Integration Tips

• Filament Panels: Works seamlessly with Filament’s admin panel. Accessible via the sidebar or URL.
• Permissions: Leverage Filament’s built-in policies to restrict access to sensitive commands (e.g., db:wipe).
• Logging: Redirect command output to Laravel’s logging system by extending the plugin:

  \TomatoPHP\FilamentArtisan\FilamentArtisanPlugin::make()
      ->outputHandler(function ($output) {
          \Log::info('Artisan Command Output:', ['output' => $output]);
      }),
  

Gotchas and Tips

Pitfalls

1. Environment Restrictions:

   • Commands default to local only. Forgetting to update config/filament-artisan.php can lock you out of running commands in other environments.
   • Fix: Explicitly whitelist environments:

     'environments' => ['local', 'staging'],
     

2. Command Arguments:

   • Not all Artisan commands support interactive argument input via the UI. Complex commands (e.g., make:model) may fail silently.
   • Fix: Use the CLI for unsupported commands or extend the plugin to handle custom forms.

3. Output Parsing:

   • Commands with ANSI colors or complex output may render poorly in the UI.
   • Fix: Override the output handler to sanitize or format logs:

     ->outputHandler(function ($output) {
         return preg_replace('/\x1B\[([0-9A-Za-z])*[mGK]?/', '', $output);
     }),
     

4. Destructive Commands:

   • Accidental execution of db:wipe or cache:clear can break production.
   • Fix: Add a confirmation step or use Filament’s policies to block access.

Debugging

• Command Not Showing?:

  • Ensure the command is registered in Laravel’s app/Console/Kernel.php.
  • Check for typos in config/filament-artisan.php under commands.
  • Verify the command isn’t hidden (e.g., hidden() in the command class).

• Blank Output:

  • Clear cached views:

    php artisan view:clear
    

  • Check PHP error logs for underlying issues.

Extension Points

1. Custom UI:

   • Override the plugin’s views by publishing assets:

     php artisan vendor:publish --tag=filament-artisan-views
     

   • Modify resources/views/vendor/filament-artisan/ to add custom fields or validation.

2. Pre/Post Hooks:

   • Extend the plugin to run logic before/after command execution:

     \TomatoPHP\FilamentArtisan\FilamentArtisanPlugin::make()
         ->beforeRun(function ($command) {
             \Log::info("Running command: {$command}");
         })
         ->afterRun(function ($output, $exitCode) {
             if ($exitCode !== 0) {
                 \Toast::danger("Command failed with exit code {$exitCode}");
             }
         }),
     

3. API Access:

   • Expose commands via Filament’s HTTP API for programmatic use:

     // In a Filament resource or page
     use TomatoPHP\FilamentArtisan\Facades\ArtisanRunner;
     
     public function runCommand()
     {
         $output = ArtisanRunner::run('migrate');
         return response()->json(['output' => $output]);
     }
     

Pro Tips

• Shortcuts: Bookmark the /artisan page for quick access to frequent commands.
• Safety: Use the --dry-run flag for destructive commands (if supported) to preview changes.
• Monitoring: Log command executions to a database table for auditing:

  ->afterRun(function ($output, $exitCode) {
      \App\Models\ArtisanLog::create([
          'command' => request('command'),
          'output' => $output,
          'exit_code' => $exitCode,
          'user_id' => auth()->id(),
      ]);
  }),