Flow Control Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devhelp/flow-control
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Devhelp\FlowControl\FlowControlServiceProvider::class,
   ],
   

2. Basic Usage Define a flow in a dedicated class (e.g., app/Flows/MyWorkflow.php):

   namespace App\Flows;
   
   use Devhelp\FlowControl\Flow;
   
   class MyWorkflow extends Flow
   {
       public function run()
       {
           $this->step('step1', function () {
               return "Step 1 executed";
           });
   
           $this->step('step2', function () {
               return "Step 2 executed";
           });
   
           $this->step('step3', function () {
               return "Step 3 executed";
           });
       }
   }
   

3. First Execution Trigger the flow from a controller or command:

   use App\Flows\MyWorkflow;
   
   $workflow = new MyWorkflow();
   $result = $workflow->execute();
   

Implementation Patterns

Workflow Design

• Modular Steps: Break complex logic into reusable steps:

  $this->step('validate', function () {
      if (!$this->validateRequest()) {
          throw new \RuntimeException("Validation failed");
      }
  });
  

• Conditional Flow:

  $this->step('conditionalStep', function () {
      if ($this->shouldProceed()) {
          return $this->process();
      }
      return null;
  });
  

Integration with Laravel

• Service Container Binding:

  $this->app->bind('workflow.my', function () {
      return new MyWorkflow();
  });
  

• Command Integration:

  use Illuminate\Console\Command;
  use App\Flows\MyWorkflow;
  
  class RunWorkflowCommand extends Command
  {
      protected $signature = 'workflow:run';
      public function handle(MyWorkflow $workflow)
      {
          $result = $workflow->execute();
          $this->info("Workflow completed: " . $result);
      }
  }
  

• Event-Driven Workflows:

  $this->step('dispatchEvent', function () {
      event(new WorkflowStepEvent($this->getStepName()));
  });
  

Data Flow

• Passing Data Between Steps:

  $this->step('fetchData', function () {
      $data = $this->getData();
      $this->setData('processed', $data);
  });
  
  $this->step('useData', function () {
      $processedData = $this->getData('processed');
      // Use $processedData
  });
  

Gotchas and Tips

Pitfalls

• Step Dependencies: Ensure steps are ordered correctly. Use before() and after() for dependencies:

  $this->step('stepA')->before('stepB');
  

• Error Handling: Uncaught exceptions in steps halt execution. Use try-catch or fail():

  $this->step('riskyStep', function () {
      try {
          // Risky logic
      } catch (\Exception $e) {
          $this->fail("Step failed: " . $e->getMessage());
      }
  });
  

• State Management: Avoid modifying shared state outside steps. Use setData()/getData() for consistency.

Debugging

• Logging: Enable debug mode in config/flow-control.php:

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

  Logs will appear in storage/logs/flow-control.log.

• Step Inspection: Use getSteps() to inspect the flow:

  $steps = $workflow->getSteps();
  dd($steps);
  

Extension Points

• Custom Step Types: Extend Devhelp\FlowControl\Step for specialized behavior:

  class CustomStep extends Step
  {
      public function execute()
      {
          // Custom logic
      }
  }
  

• Middleware: Add middleware to steps:

  $this->step('authStep')->middleware(AuthMiddleware::class);
  

• Configuration: Override defaults in config/flow-control.php:

  'default_timeout' => 30, // seconds
  'max_retries' => 3,