Runtime Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require boson-php/runtime
   

   No additional configuration is required for basic usage.

2. First Use Case: Runtime Execution The package provides a lightweight runtime environment for executing Boson workflows (a state machine/DSL for business logic). Start with a simple workflow definition:

   use Boson\Runtime\Runtime;
   
   $runtime = new Runtime();
   $result = $runtime->run('workflow_id', ['input' => 'data']);
   

3. Where to Look First

   • Documentation: Check the Boson PHP repo for workflow syntax and examples.
   • Runtime Class: Focus on Boson\Runtime\Runtime for execution logic.
   • Workflow Files: Store workflows as JSON/YAML files (e.g., resources/workflows/example.json) and load them dynamically.

Implementation Patterns

Workflow Integration

1. Dynamic Workflow Loading Load workflows from files or databases:

   $workflow = json_decode(file_get_contents('path/to/workflow.json'), true);
   $runtime->loadWorkflow('workflow_id', $workflow);
   

2. Input/Output Handling Pass structured input and capture outputs:

   $output = $runtime->run('workflow_id', [
       'user_id' => 123,
       'action' => 'process_order'
   ]);
   

3. Error Handling Wrap runtime calls in try-catch:

   try {
       $runtime->run('workflow_id', $input);
   } catch (\Boson\Runtime\Exception\WorkflowException $e) {
       Log::error("Workflow failed: " . $e->getMessage());
   }
   

Laravel-Specific Patterns

1. Service Provider Binding Bind the runtime as a singleton in AppServiceProvider:

   $this->app->singleton(Runtime::class, function ($app) {
       return new Runtime();
   });
   

2. Artisan Commands Create a command to trigger workflows:

   use Boson\Runtime\Runtime;
   
   class RunWorkflowCommand extends Command {
       protected $signature = 'workflow:run {id} {--input=}';
       public function handle(Runtime $runtime) {
           $input = json_decode($this->option('input'), true);
           $result = $runtime->run($this->argument('id'), $input);
           $this->info($result);
       }
   }
   

3. Event Listeners Hook into workflow completion:

   $runtime->on('workflow_completed', function ($workflowId, $output) {
       event(new WorkflowCompleted($workflowId, $output));
   });
   

Gotchas and Tips

Pitfalls

1. Workflow Validation

   • The runtime expects valid Boson workflow syntax. Invalid JSON/YAML will throw WorkflowException.
   • Tip: Validate workflows before loading them:

     $validator = new \Boson\Runtime\Validator();
     if (!$validator->validate($workflow)) {
         throw new \InvalidArgumentException("Invalid workflow");
     }
     

2. State Management

   • Workflows are stateless by default. Use external storage (e.g., Redis) for persistent state if needed.
   • Tip: Extend Runtime to support stateful workflows:

     $runtime->setStateStore(new RedisStateStore());
     

3. Performance

   • Complex workflows may cause high memory usage. Optimize by:
     • Breaking workflows into smaller steps.
     • Using lazy evaluation for large datasets.

Debugging

1. Enable Verbose Logging Set the runtime log level:

   $runtime->setLogLevel(\Monolog\Logger::DEBUG);
   

2. Inspect Workflow Steps Use Runtime::getDebugInfo() to trace execution:

   $debugInfo = $runtime->getDebugInfo();
   dd($debugInfo['steps']); // Array of executed steps
   

Extension Points

1. Custom Actions Register custom actions (e.g., database queries):

   $runtime->registerAction('custom_action', function ($input) {
       return Model::where('id', $input['id'])->first();
   });
   

2. Middleware Add pre/post-processing middleware:

   $runtime->pushMiddleware(function ($workflow, $input, $next) {
       $input['timestamp'] = now()->toDateTimeString();
       return $next($workflow, $input);
   });
   

3. Plugin System The package is designed for extension. Fork and modify Runtime to add:

   • Caching layers.
   • Distributed execution (e.g., queues).
   • Custom serialization formats.