Filament Workflows Laravel Package

Getting Started

Minimal Steps to First Workflow

1. Install & Publish:

   composer require monzer/filament-workflows
   php artisan vendor:publish --provider="Monzer\FilamentWorkflows\FilamentWorkflowsServiceProvider" --tag="migrations"
   php artisan migrate
   

   Run php artisan vendor:publish --provider="Monzer\FilamentWorkflows\FilamentWorkflowsServiceProvider" --tag="config" if customizing defaults.

2. Access the Workflow Resource: Navigate to /admin/resources/workflows in your Filament admin panel to create your first workflow.

3. First Use Case: Model Event Trigger

   • Create a workflow targeting a model (e.g., Order).
   • Define a trigger: Select model.created (or any other event like model.updated).
   • Add an action (e.g., "Send Email" or "Update Related Model").
   • Use Magic Attributes (e.g., {model.name}) to dynamically bind data.
   • Save and test by creating/updating a model.

Implementation Patterns

Core Workflows

1. Model Event Automation:

   • Attach workflows to model events (e.g., created, updated, deleted) via the Filament UI.
   • Example: Automate sending a welcome email when a User is created.

     // In your Workflow definition (via UI):
     // Trigger: User created
     // Action: Send Email (to: {model.email}, subject: "Welcome!")
     

2. Scheduled Tasks:

   • Use the "Run on Schedule" trigger to execute workflows periodically (e.g., daily reports).
   • Configure cron expressions in the workflow settings (e.g., 0 0 * * * for daily at midnight).

3. Custom Event Integration:

   • Dispatch custom events in your app and link them to workflows.
   • Example:

     // In your event listener:
     event(new OrderPaid($order));
     
     // In Filament Workflows UI:
     // Trigger: OrderPaid (custom event)
     // Action: Update inventory ({model.product_id}, quantity: -{event.amount})
     

4. Chaining Actions:

   • Combine multiple actions (e.g., send email → update status → log activity) in a single workflow.
   • Use the "Add Action" button in the workflow editor to stack actions sequentially.

5. Webhook Integrations:

   • Send HTTP requests to external APIs (e.g., Slack, Stripe) using the "Send Webhook" action.
   • Configure the endpoint URL, method (POST/GET), and payload (e.g., {model.id}).

Integration Tips

1. Magic Attributes:

   • Dynamically inject model/event data into actions using placeholders like:
     • {model.attribute} (e.g., {model.name})
     • {event.data} (for custom events)
     • {workflow.name} (metadata)
   • Preview replacements in the Filament UI before saving.

2. Custom Actions:

   • Extend functionality by creating custom actions. Example:

     namespace App\Actions;
     
     use Monzer\FilamentWorkflows\Actions\Action;
     
     class CustomAction extends Action
     {
         public static function getName(): string
         {
             return 'Custom Logic';
         }
     
         public function handle(): void
         {
             // Your custom logic here
             \Log::info('Custom action triggered for model: ' . $this->model->id);
         }
     }
     

   • Register the action in config/filament-workflows.php under actions.custom.

3. Conditional Logic:

   • Use the "If" condition in workflows to branch logic (e.g., only send an email if model.status === 'paid').
   • Conditions support Magic Attributes (e.g., {model.status} === 'active').

4. Error Handling:

   • Enable "Stop on Failure" in workflow settings to halt execution if an action fails.
   • View execution logs in the Filament Workflow Resource under the "Logs" tab.

5. Testing:

   • Test workflows locally by triggering model events or dispatching custom events.
   • Use Tinker to simulate events:

     php artisan tinker
     >>> \App\Models\User::create(['name' => 'Test User']);
     

Gotchas and Tips

Pitfalls

1. Magic Attribute Parsing:

   • Issue: Placeholders like {model.non_existent} will break workflows.
   • Fix: Validate Magic Attributes in the UI before saving or use a fallback (e.g., {model.attribute|default:'fallback'}).

2. Circular Dependencies:

   • Issue: Workflows triggering other workflows can cause infinite loops.
   • Fix: Avoid recursive triggers or use a "cooldown" period in scheduled workflows.

3. Performance:

   • Issue: Complex workflows with many actions may slow down event handling.
   • Fix: Offload heavy tasks to queues (e.g., use Laravel Queues for email actions).

4. Webhook Timeouts:

   • Issue: External API timeouts may fail silently.
   • Fix: Configure retry logic in the "Send Webhook" action or use a queue.

5. Permission Issues:

   • Issue: Workflows may fail if the Filament user lacks permissions.
   • Fix: Assign appropriate roles to the Filament user running workflows.

Debugging

1. Execution Logs:

   • Check /admin/resources/workflows/{workflow}/logs for errors or successful runs.
   • Logs include timestamps, action names, and output (e.g., HTTP responses for webhooks).

2. Event Listeners:

   • Verify events are dispatched correctly:

     // Add a temporary listener for debugging:
     \Event::listen(\App\Events\OrderPaid::class, function ($event) {
         \Log::info('OrderPaid event fired for order: ' . $event->order->id);
     });
     

3. Magic Attribute Debugging:

   • Use {{ dump({model}) }} in Blade templates (if applicable) to inspect model data.
   • Test placeholders in the Filament UI preview.

Extension Points

1. Custom Triggers:

   • Extend the Trigger class to support custom event sources (e.g., database changes via Laravel Observers).
   • Example:

     namespace App\Triggers;
     
     use Monzer\FilamentWorkflows\Triggers\Trigger;
     
     class DatabaseChangeTrigger extends Trigger
     {
         public static function getName(): string
         {
             return 'Database Change';
         }
     
         public function shouldRun(): bool
         {
             return \DB::table('changes')->where('model', $this->model)->exists();
         }
     }
     

   • Register in config/filament-workflows.php under triggers.custom.

2. Action Metadata:

   • Add metadata to actions (e.g., icons, descriptions) for better UX:

     class SendEmailAction extends Action
     {
         public static function getName(): string
         {
             return 'Send Email';
         }
     
         public static function getDescription(): string
         {
             return 'Send an email using the model data.';
         }
     
         public static function getIcon(): string
         {
             return 'heroicon-o-envelope';
         }
     }
     

3. Workflow Hooks:

   • Listen to workflow events (e.g., workflow.starting, workflow.failed) via Laravel Events:

     \Event::listen(\Monzer\FilamentWorkflows\Events\WorkflowStarting::class, function ($event) {
         \Log::info("Workflow {$event->workflow->name} is starting for model {$event->model->id}");
     });
     

4. Localization:

   • Override default labels (e.g., "Actions", "Triggers") by publishing the language file:

     php artisan vendor:publish --provider="Monzer\FilamentWorkflows\FilamentWorkflowsServiceProvider" --tag="lang"
     

   • Edit resources/lang/en/filament-workflows.php.

Config Quirks

1. Queue Configuration:

   • Workflows run synchronously by default. To use queues:

     // config/filament-workflows.php
     'queue' => [
         'enabled' => true,
         'connection' => 'redis',
     ],
     

   • Ensure your queue worker is running (php artisan queue:work).

2. Default Workflow Settings:

   • Customize defaults (e.g., stop on failure, retry attempts) in config/filament-workflows.php:

     'defaults' => [
         'stop_on_failure' => true,
         'max_retries' => 3,
     ],
     

3. Model Binding:

   • Ensure workflows are bound to the correct model class. Misconfigurations may cause ModelNotFound errors.
   • Verify the model namespace in the workflow editor (e.g., App\Models\User).