Flowforge Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alizharb/forgepulse
   php artisan forgepulse:install
   

   Runs migrations and publishes config/assets.

2. First Workflow

   php artisan forgepulse:make-workflow OrderProcessing
   

   Creates a scaffolded workflow with:

   • Basic UI components
   • Default execute() method
   • Database table

3. Access Designer Visit /forgepulse/workflows in your browser. The drag-and-drop editor appears immediately.

First Use Case: Simple Approval Flow

1. Add a "Start" node (auto-created)
2. Drag-and-drop an "Action" node (e.g., SendEmail)
3. Connect nodes with the mouse
4. Click "Save" → Workflow is stored in workflow_nodes table

Implementation Patterns

Core Workflow Patterns

1. Node-Based Architecture

   // Define custom action node
   class SendEmailNode extends ActionNode
   {
       public function execute(Workflow $workflow, array $data)
       {
           Mail::to($data['email'])->send(new OrderEmail($data));
           return ['status' => 'sent'];
       }
   }
   

   • Extend BaseNode for custom logic
   • Implement execute() for runtime behavior

2. Conditional Branching

   // In designer: Add "Condition" node
   // Set rule: `{{ $data->amount > 1000 }}`
   // Connect "Yes" and "No" paths
   

   • Uses Laravel Blade syntax for conditions
   • Supports 22+ operators (e.g., in, contains, date comparisons)

3. Workflow Execution

   $workflow = Workflow::find(1);
   $result = $workflow->execute(['order_id' => 123, 'amount' => 500]);
   

   • Returns array of node outputs
   • Throws WorkflowException on failures

Integration Workflows

1. API-Driven Triggers

   Route::post('/orders/{id}/process', function ($id) {
       $workflow = Workflow::where('slug', 'order-processing')->first();
       return $workflow->execute(['order_id' => $id]);
   });
   

2. Queue Background Jobs

   $workflow->executeLater(['user_id' => 1], 'high');
   // Uses Laravel Queues (supports `sync`, `database`, `redis`)
   

3. Event Listeners

   // Trigger workflow on model event
   OrderCreated::class => [
       function ($order) {
           Workflow::where('slug', 'post-order')->first()
               ->execute(['order' => $order]);
       }
   ];
   

4. Real-Time Tracking

   // Subscribe to workflow events
   event(new WorkflowStarted($workflow));
   // Listen via Pusher/Broadcast
   

Gotchas and Tips

Common Pitfalls

1. Node Registration

   • Issue: Custom nodes not appearing in designer.
   • Fix: Ensure registerNodes() is called in a service provider:

     ForgePulse::registerNodes([
         \App\Nodes\SendEmailNode::class,
     ]);
     

2. Data Serialization

   • Issue: Complex objects fail during execution.
   • Fix: Use serialize()/unserialize() or cast to arrays:

     $data = ['user' => $user->toArray()];
     

3. Versioning Conflicts

   • Issue: Concurrent edits overwrite changes.
   • Fix: Use workflow()->lockForUpdate() in custom logic.

4. Livewire Caching

   • Issue: Designer UI glitches after node additions.
   • Fix: Clear Livewire cache:

     php artisan livewire:discover
     

Pro Tips

1. Debugging Workflows

   • Enable logging in config/forgepulse.php:

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

   • View execution logs at /forgepulse/logs.

2. Performance Optimization

   • Tip: Cache workflow definitions:

     $workflow = Workflow::find(1)->load('nodes');
     

   • Use ->withoutEvents() for bulk operations.

3. Extending UI

   • Customize the designer via resources/views/vendor/forgepulse/...
   • Override Alpine.js components in resources/js/forgepulse.js.

4. Testing Strategies

   • Mock nodes in unit tests:

     $node = Mockery::mock(SendEmailNode::class);
     $node->shouldReceive('execute')->andReturn(['success' => true]);
     

   • Use WorkflowTestCase trait for integration tests.

5. Conditional Logic Quirks

   • Tip: Use {{ $data->property }} (not $data['property']) in conditions.
   • Workaround: For arrays, use {{ $data->property->contains('value') }}.

6. Rollback Safety

   • Tip: Test version rollbacks in staging:

     $workflow->rollbackToVersion(2);
     

   • Verify data integrity post-rollback.

7. Keyboard Shortcuts

   • Undo/Redo: Cmd+Z / Cmd+Shift+Z
   • Delete Node: Backspace
   • Zoom: Cmd+Mouse Wheel