Forgepulse Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alizharb/forgepulse
   php artisan vendor:publish --provider="AlizHarb\ForgePulse\ForgePulseServiceProvider" --tag="forgepulse-migrations"
   php artisan migrate
   

2. Basic Usage

   • Access the workflow designer at /forgepulse (Livewire-powered UI).
   • Create a workflow via the UI or programmatically:

     use AlizHarb\ForgePulse\Models\Workflow;
     
     $workflow = Workflow::create([
         'name' => 'User Onboarding',
         'description' => 'Guide new users through setup',
     ]);
     

3. First Workflow Execution

   use AlizHarb\ForgePulse\Facades\ForgePulse;
   
   $execution = ForgePulse::execute($workflow, ['user_id' => 1]);
   

Where to Look First

• Documentation: Features & Screenshots for UI/UX details.
• Migrations: Check database/migrations/ for schema changes.
• Livewire Components: resources/views/vendor/forgepulse/ for customization hooks.

Implementation Patterns

Core Workflows

1. UI-Driven Development

   • Design workflows visually in the /forgepulse dashboard.
   • Use the drag-and-drop interface to add steps (e.g., Email, Database, API Call).
   • Configure conditional branching via the UI (e.g., "If user is premium, skip step X").

2. Programmatic Workflow Creation

   $workflow = Workflow::create([
       'name' => 'Order Processing',
       'steps' => [
           ['type' => 'email', 'template' => 'order_confirmation', 'to' => '{{ user.email }}'],
           ['type' => 'database', 'query' => 'UPDATE orders SET status = ? WHERE id = ?', 'params' => ['shipped', 123]],
       ],
   ]);
   

3. Execution Patterns

   • Synchronous:

     $result = ForgePulse::execute($workflow, $context);
     

   • Asynchronous (via queues):

     ForgePulse::queueExecution($workflow, $context);
     

   • Real-Time Tracking:

     $execution = ForgePulse::startExecution($workflow, $context);
     $execution->onProgress(fn ($step) => Log::info("Step completed: {$step['name']}"));
     

4. Conditional Logic

   • Define rules in the UI or via JSON:

     'conditions' => [
         ['field' => 'user.tier', 'operator' => '>', 'value' => 'basic', 'next_step' => 3],
     ],
     

5. Integration with Laravel Ecosystem

   • Events: Listen to WorkflowExecuted, StepFailed:

     event(new WorkflowExecuted($execution));
     

   • Notifications: Trigger alerts via ForgePulse::notify($execution, 'step_failed').
   • Jobs: Extend ForgePulse\Jobs\ExecuteStep for custom step logic.

Gotchas and Tips

Pitfalls

1. State Management

   • Workflows are stateful by default. Clear context data between executions:

     $execution->resetContext(); // Resets all variables.
     

   • Gotcha: Conditional branches rely on context variables. Ensure they’re populated before execution.

2. UI vs. Programmatic Sync

   • Changes made in the UI do not automatically update programmatic workflows. Use:

     $workflow->refreshFromDatabase(); // Syncs UI-defined steps.
     

3. Versioning Quirks

   • Workflow versions are immutable. Rollback requires:

     $workflow->revertToVersion(2); // Reverts to version 2.
     

   • Warning: Reverted versions do not trigger new executions.

4. Performance

   • Complex workflows with >50 steps may time out. Use chunked execution:

     ForgePulse::executeInChunks($workflow, $context, 10); // 10 steps per chunk.
     

5. Livewire Conflicts

   • If the UI lags, check for:
     • Alpine.js version conflicts (use ^3.12).
     • Livewire 4 compatibility (ForgePulse requires ^4.0).

Debugging Tips

1. Execution Logs

   • Enable debug mode:

     config(['forgepulse.debug' => true]);
     

   • Check storage/logs/forgepulse.log for step-by-step execution traces.

2. Conditional Debugging

   • Dump conditions before execution:

     dd($workflow->steps, $context); // Verify data matches expectations.
     

3. UI Debugging

   • Disable CSS/JS minification for development:

     FORGEPULSE_DEBUG_UI=true
     

Extension Points

1. Custom Steps

   • Create a step class:

     namespace App\ForgePulse\Steps;
     
     use AlizHarb\ForgePulse\Contracts\Step;
     
     class CustomStep implements Step {
         public function execute($context) { ... }
     }
     

   • Register it in config/forgepulse.php:

     'steps' => [
         'custom' => \App\ForgePulse\Steps\CustomStep::class,
     ],
     

2. Middleware

   • Add pre/post-execution logic:

     ForgePulse::beforeExecute(fn ($workflow, $context) => {
         // Validate context.
     });
     

3. Storage Drivers

   • Extend storage (e.g., S3 for large workflows):

     ForgePulse::extendStorage('s3', function () {
         return new S3WorkflowStorage();
     });
     

4. Testing

   • Use the ForgePulseTestCase trait:

     use AlizHarb\ForgePulse\Testing\ForgePulseTestCase;
     
     class WorkflowTest extends ForgePulseTestCase {
         public function testExecution() {
             $this->executeWorkflow('user_onboarding', ['user_id' => 1]);
         }
     }