Bpm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require 2lenet/bpm-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Lle\BpmBundle\LleBpmBundle::class => ['all' => true],
   ];
   

2. Routing Import the default routes in config/routes.yaml:

   bpm:
       resource: "@LleBpmBundle/Resources/config/routing/routes.yaml"
       prefix: /admin/bpm
   

   (Note: Adjust prefix to avoid conflicts with existing admin routes.)

3. First Use Case Define a simple workflow in a YAML file (e.g., config/bpm/workflows/example_workflow.yaml):

   example_workflow:
       start: initial_state
       states:
           initial_state:
               transitions:
                   approve: approved_state
           approved_state: {}
   

   Register the workflow in services.yaml:

   lle_bpm.workflows:
       example_workflow: ~
   

4. Basic Usage in Controller

   use Lle\BpmBundle\Workflow\WorkflowManager;
   
   public function startWorkflow(WorkflowManager $workflowManager)
   {
       $workflow = $workflowManager->getWorkflow('example_workflow');
       $workflow->start(); // Trigger initial state
   }
   

Implementation Patterns

Workflow Definition

1. YAML-Based Workflows Define workflows in config/bpm/workflows/*.yaml with:

   • States: Named nodes with optional on_enter/on_exit callbacks.
   • Transitions: Named edges between states (e.g., approve: next_state).
   • Guard Conditions: Use PHP closures for dynamic validation:

     transitions:
         approve:
             to: approved_state
             guard: "@= user.hasPermission('APPROVE')"
     

2. Dynamic Workflows Load workflows programmatically:

   $workflowManager->loadWorkflowFromYaml(file_get_contents('custom_path.yaml'));
   

Integration with Symfony

1. Event Listeners Hook into workflow events (e.g., WorkflowStateChangedEvent):

   use Lle\BpmBundle\Event\WorkflowEvent;
   
   public function onStateChanged(WorkflowEvent $event)
   {
       if ($event->getNewState() === 'approved') {
           $this->mailer->sendApprovalEmail($event->getWorkflow());
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\WorkflowListener:
           tags:
               - { name: kernel.event_listener, event: lle_bpm.workflow.state_changed }
   

2. Doctrine Entities Attach workflows to entities via annotations or metadata:

   use Lle\BpmBundle\Annotation\Workflow;
   
   /**
    * @Workflow("example_workflow")
    */
   class Order {}
   

   (Note: Bundle may require manual setup for Doctrine integration.)

API-Driven Workflows

1. RESTful Transitions Expose workflow transitions via API:

   public function transition(WorkflowManager $workflowManager, string $transition, string $entityId)
   {
       $workflow = $workflowManager->getWorkflowForEntity($entityId);
       $workflow->transition($transition);
       return new JsonResponse(['status' => 'transited']);
   }
   

2. State Validation Validate transitions before execution:

   try {
       $workflow->canTransition($transition) // Check guard conditions
           ->transition($transition);
   } catch (WorkflowException $e) {
       return new JsonResponse(['error' => $e->getMessage()], 403);
   }
   

Gotchas and Tips

Configuration Quirks

1. Routing Conflicts

   • Default routes (/admin/bpm) may clash with existing admin panels.
   • Fix: Override the prefix in config/routes.yaml or extend the bundle’s routing.

2. YAML Parsing

   • The bundle uses Symfony’s YAML component, but complex expressions (e.g., @=) may fail silently.
   • Tip: Validate YAML with symfony/var-dumper:

     use Symfony\Component\Yaml\Yaml;
     $config = Yaml::parse(file_get_contents('workflow.yaml'));
     

3. Workflow Caching

   • Workflows are cached by default. Clear cache after changes:

     php bin/console cache:clear
     

Debugging

1. State Transitions

   • Use WorkflowManager::getWorkflowHistory() to audit transitions:

     $history = $workflowManager->getWorkflowHistory($workflowId);
     

   • Tip: Log transitions in a listener for debugging:

     $this->logger->info('Transitioned to {$event->getNewState()}', ['workflow' => $event->getWorkflow()->getId()]);
     

2. Guard Conditions

   • Guards failing silently? Enable debug mode in config/packages/lle_bpm.yaml:

     debug: true
     

   • Tip: Test guards in isolation:

     $guard = $workflow->getTransitionGuard('approve');
     var_dump($guard->__invoke($workflow)); // Returns bool
     

Extension Points

1. Custom States/Transitions

   • Extend core classes (e.g., State, Transition) for custom logic:

     class CustomState extends \Lle\BpmBundle\Workflow\State
     {
         public function onEnter(Workflow $workflow)
         {
             // Custom logic
         }
     }
     

   • Register in services.yaml:

     Lle\BpmBundle\Workflow\State: '@App\Workflow\CustomState'
     

2. Database Backend

   • The bundle lacks built-in DB persistence. Use Doctrine listeners to sync workflows:

     public function prePersist(LifecycleEventArgs $args)
     {
         $entity = $args->getObject();
         if ($entity instanceof WorkflowEntity) {
             $workflow = $this->workflowManager->getWorkflowForEntity($entity);
             $entity->setCurrentState($workflow->getCurrentState());
         }
     }
     

3. Legacy Code

   • Tip: Wrap legacy state machines in adapters to leverage BPM features:

     class LegacyAdapter implements WorkflowInterface
     {
         public function transition(string $transition)
         {
             // Call legacy logic
         }
     }