Workflow Engine Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require solution-forest/workflow-engine-laravel
   php artisan vendor:publish --provider="SolutionForest\WorkflowEngine\Providers\WorkflowEngineServiceProvider"
   

2. Define a Workflow Create a workflow enum (app/Enums/ExampleWorkflow.php):

   namespace App\Enums;
   
   use SolutionForest\WorkflowEngine\Attributes\Workflow;
   use SolutionForest\WorkflowEngine\Workflow\WorkflowDefinition;
   
   #[Workflow]
   enum ExampleWorkflow: string
   {
       case INITIALIZE = 'initialize';
       case PROCESS = 'process';
       case FINALIZE = 'finalize';
   
       public function definition(): WorkflowDefinition
       {
           return WorkflowDefinition::create()
               ->from(self::INITIALIZE)
               ->to(self::PROCESS)
               ->to(self::FINALIZE);
       }
   }
   

3. First Use Case Trigger a workflow in a controller:

   use SolutionForest\WorkflowEngine\Facades\WorkflowEngine;
   
   public function startWorkflow()
   {
       $workflow = WorkflowEngine::create(ExampleWorkflow::INITIALIZE);
       $workflow->execute();
   }
   

Where to Look First

• Documentation: Check config/workflow-engine.php for core settings.
• Artisan Commands: Run php artisan workflow:list to inspect registered workflows.
• Attributes: Review SolutionForest\WorkflowEngine\Attributes for decorators like #[WorkflowStep].

Implementation Patterns

Core Workflow Patterns

1. Step-Based Execution Define steps with attributes:

   #[WorkflowStep(ExampleWorkflow::PROCESS)]
   public function handleProcessing(WorkflowContext $context)
   {
       // Business logic here
       $context->transitionTo(ExampleWorkflow::FINALIZE);
   }
   

2. Event-Driven Workflows Listen to workflow events:

   WorkflowEngine::on('workflow.started', fn ($event) => {
       Log::info("Workflow started: {$event->workflow->name}");
   });
   

3. Retry & Timeout Policies Apply retry logic to steps:

   #[Retry(maxAttempts: 3, delay: 1000)]
   #[Timeout(seconds: 30)]
   #[WorkflowStep(ExampleWorkflow::PROCESS)]
   public function handleProcessing(WorkflowContext $context)
   {
       // ...
   }
   

Integration Tips

• Eloquent Models: Attach workflows to models via traits:

  use SolutionForest\WorkflowEngine\Eloquent\HasWorkflows;
  
  class Order extends Model
  {
      use HasWorkflows;
  
      protected $workflowClass = ExampleWorkflow::class;
  }
  

• Queue Jobs: Offload workflow steps to queues:

  WorkflowEngine::create(ExampleWorkflow::INITIALIZE)
      ->queue()
      ->execute();
  

• Testing: Use the WorkflowTestCase base class:

  use SolutionForest\WorkflowEngine\Testing\WorkflowTestCase;
  
  class ExampleWorkflowTest extends WorkflowTestCase
  {
      public function test_workflow_execution()
      {
          $this->assertWorkflowExecutes(ExampleWorkflow::INITIALIZE);
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Attribute Registration

   • Forgetting to register workflow enums in config/workflow-engine.php under workflows.
   • Fix: Add your enum to the workflows array:

     'workflows' => [
         ExampleWorkflow::class,
     ],
     

2. Type Safety Mismatches

   • Using incorrect enum values in transitions can cause silent failures.
   • Tip: Enable strict typing in php.ini and use IDE autocompletion for enums.

3. Circular Dependencies

   • Workflows with circular transitions (e.g., A → B → A) will throw WorkflowException.
   • Solution: Validate workflow definitions with:

     $definition = ExampleWorkflow::INITIALIZE->definition();
     $definition->validate();
     

4. Context Serialization

   • Workflow context data must be JSON-serializable.
   • Workaround: Use JsonSerializable or cast complex objects to arrays.

Debugging Tips

• Log Workflow Events: Enable debug logging in config/workflow-engine.php:

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

• Inspect State: Use php artisan workflow:inspect <workflow_id> to debug stuck workflows.
• Step Tracing: Add #[WorkflowStep(log: true)] to log step execution details.

Extension Points

1. Custom Step Handlers Extend the WorkflowStepHandler interface to add custom logic:

   class CustomStepHandler implements WorkflowStepHandler
   {
       public function handle(WorkflowContext $context, string $step): void
       {
           // Custom logic
       }
   }
   

2. Middleware Add middleware to workflow execution:

   WorkflowEngine::middleware(function ($workflow, $next) {
       // Pre-execution logic
       return $next($workflow);
   });
   

3. Storage Backends Override the default database storage by binding a custom WorkflowRepository:

   $this->app->bind(WorkflowRepository::class, function ($app) {
       return new CustomWorkflowRepository();
   });
   

Performance Considerations

• Batch Processing: Use WorkflowEngine::batch() to process multiple workflows efficiently.
• Caching: Cache workflow definitions if they rarely change:

  WorkflowEngine::cacheDefinitions(true);