Eav Process Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (though archived, ensure compatibility with your Laravel/Eloquent setup):

   composer require cleverage/eav-process-bundle
   

   Register the bundle in config/app.php under providers (if using Symfony/Laravel bridge):

   CleverAge\EAVProcessBundle\CleverAgeEAVProcessBundle::class
   

2. First Use Case: Process Definition Define a process in config/eav_processes.php (or via YAML/XML if supported):

   'processes' => [
       'user_approval' => [
           'steps' => [
               'submit' => ['handler' => 'App\Handlers\SubmitStep'],
               'review' => ['handler' => 'App\Handlers\ReviewStep'],
           ],
       ],
   ],
   

3. Triggering a Process Inject the ProcessManager and start a process:

   $process = $processManager->create('user_approval', $entityId);
   $process->execute(); // Runs steps sequentially
   

Implementation Patterns

Workflow Integration

1. Event-Driven Processes Hook into ProcessStarted, StepExecuted, or ProcessCompleted events (if event system exists):

   event(new ProcessStarted($process));
   

2. Step Handlers Implement ProcessStepInterface for custom logic:

   class SubmitStep implements ProcessStepInterface {
       public function execute($entity, array $context) {
           // Business logic (e.g., validate, persist)
           return ['status' => 'submitted'];
       }
   }
   

3. Context Passing Pass data between steps via $context array:

   // Step 1
   $context['reviewer_id'] = 123;
   
   // Step 2 (access via $context)
   $reviewer = User::find($context['reviewer_id']);
   

4. Conditional Steps Dynamically add steps based on runtime conditions:

   if ($entity->isUrgent()) {
       $process->addStep('priority_review', ['handler' => 'App\Handlers\UrgentReview']);
   }
   

Laravel-Specific Tips

• Service Container Binding Bind custom step handlers as singletons:

  $this->app->singleton('App\Handlers\ReviewStep');
  

• Database Integration Store process state in a processes table (if not using EAVManager):

  Schema::create('processes', function (Blueprint $table) {
      $table->id();
      $table->string('name');
      $table->json('context');
      $table->string('current_step');
      $table->timestamps();
  });
  

• Queueable Processes Dispatch long-running processes to queues:

  ProcessJob::dispatch($process)->onQueue('processes');
  

Gotchas and Tips

Pitfalls

1. Archived Package Risks

   • No active maintenance; test thoroughly with your Laravel version.
   • Fork or patch if critical bugs arise (e.g., PHP 8.x compatibility).

2. State Management

   • Processes are stateless by default. Use a database or cache to persist context between executions.
   • Example: Store $process->getContext() in session() or Redis.

3. Error Handling

   • Steps throw exceptions silently. Wrap in try-catch:

     try {
         $process->execute();
     } catch (ProcessException $e) {
         $process->markFailed($e->getMessage());
     }
     

4. Circular Dependencies Avoid steps that reference each other (e.g., step_a calls step_b, which calls step_a).

Debugging

• Log Context Dump $process->getContext() at each step for debugging:

  \Log::debug('Current context:', $context);
  

• Step Isolation Test steps in isolation:

  $handler = new SubmitStep();
  $result = $handler->execute($entity, []);
  

Extension Points

1. Custom Process Storage Override ProcessManager to use your preferred storage (e.g., DynamoDB):

   class CustomProcessManager extends ProcessManager {
       public function save(Process $process) {
           // Custom logic
       }
   }
   

2. Validation Add validation to steps using Laravel’s Validator:

   $validator = Validator::make($context, [
       'reviewer_id' => 'required|exists:users,id',
   ]);
   

3. Retry Mechanism Implement retries for failed steps:

   if ($process->hasFailed()) {
       $process->retry(); // Re-execute last step
   }
   

Configuration Quirks

• Process Naming Use kebab-case for process names (e.g., user_approval) to avoid issues with YAML/XML parsing.
• Handler Autowiring Ensure handlers are autowireable (e.g., no hardcoded container calls).