Workflower Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require phpmentors/workflower-bundle "1.4.*"
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   return [
       // ...
       PHPMentors\WorkflowerBundle\PHPMentorsWorkflowerBundle::class => ['all' => true],
   ];
   

2. Configure Workflower Add a workflower.yaml config file in config/packages/:

   phpmentors_workflower:
       contexts:
           default:
               bpmn_directory: '%kernel.project_dir%/config/workflows'
               serializer: 'phpmentors_workflower.serializer.doctrine'
   

3. First Use Case: Define a Workflow

   • Place a .bpmn file (e.g., order_processing.bpmn) in config/workflows/default/.
   • Define a process-aware service (e.g., OrderProcessService) with the @phpmentors_workflower.process_aware tag:

     use PHPMentors\WorkflowerBundle\Annotation\ProcessAware;
     
     class OrderProcessService {
         /**
          * @ProcessAware(process="order_processing")
          */
         public function startOrderProcess(Order $order) { ... }
     }
     

4. Trigger a Workflow Inject the Workflower service and call:

   $workflower = $this->container->get('phpmentors_workflower.workflower');
   $workflower->startProcess('order_processing', ['orderId' => $order->id]);
   

Implementation Patterns

Workflow Integration Workflows

1. Process-Aware Services

   • Tag services with @ProcessAware to bind them to BPMN processes.
   • Useful for domain-specific workflows (e.g., InvoiceService for invoice_workflow).
   • Example:

     class InvoiceService {
         /**
          * @ProcessAware(process="invoice_workflow")
          */
         public function generateInvoice(Invoice $invoice) {
             // Workflower will handle the process flow here.
         }
     }
     

2. Context Management

   • Use multiple contexts (directories) for environment-specific workflows (e.g., dev, prod).
   • Configure in workflower.yaml:

     phpmentors_workflower:
         contexts:
             dev:
                 bpmn_directory: '%kernel.project_dir%/config/workflows/dev'
             prod:
                 bpmn_directory: '%kernel.project_dir%/config/workflows/prod'
     

   • Switch contexts dynamically:

     $workflower->setContext('prod');
     

3. Entity Serialization

   • Leverage Doctrine ORM serialization for entities involved in workflows.
   • Ensure entities implement Serializable or use @Serializer annotations:

     use PHPMentors\WorkflowerBundle\Annotation\Serializer;
     
     class Order implements \Serializable {
         /**
          * @Serializer
          */
         public function serialize() { ... }
     }
     

4. Security Integration

   • Restrict workflow participants using Symfony’s security system.
   • Configure roles in workflower.yaml:

     phpmentors_workflower:
         security:
             roles:
                 start_order_process: ROLE_ADMIN
     

   • Check permissions in process-aware methods:

     if (!$this->isGranted('start_order_process')) {
         throw new \RuntimeException('Unauthorized');
     }
     

5. Event Listeners

   • Attach listeners to workflow events (e.g., ProcessStarted, ActivityExecuted).
   • Example:

     use PHPMentors\WorkflowerBundle\Event\ProcessStartedEvent;
     
     $eventDispatcher->addListener(
         'workflower.process.started',
         function (ProcessStartedEvent $event) {
             // Log or notify when a process starts.
         }
     );
     

Gotchas and Tips

Pitfalls

1. BPMN File Paths

   • Ensure bpmn_directory in workflower.yaml is absolute and points to a valid directory.
   • Debugging tip: Use %kernel.project_dir% for cross-environment consistency.

2. Serialization Issues

   • Entities passed to workflows must be serializable. Use @Serializer or implement \Serializable.
   • Avoid circular references in entities (e.g., Order ↔ Customer with bidirectional relations).

3. Process-Aware Tag Misconfiguration

   • The @ProcessAware annotation must match a .bpmn file in the configured directory.
   • Verify the process attribute in the annotation matches the BPMN file name (without .bpmn).

4. Context Switching

   • Workflower does not automatically switch contexts. Call $workflower->setContext('name') explicitly.
   • Contexts are not thread-safe; ensure proper isolation in multi-threaded environments.

5. Doctrine Integration

   • If using Doctrine, ensure the phpmentors_workflower.serializer.doctrine service is registered.
   • For custom serializers, implement PHPMentors\WorkflowerBundle\Serializer\SerializerInterface.

Debugging Tips

1. Enable Workflower Logging Add to config/packages/dev/monolog.yaml:

   handlers:
       workflower:
           type: stream
           path: '%kernel.logs_dir%/workflower.log'
           level: debug
           channels: ['workflower']
   

   Then configure the channel in workflower.yaml:

   phpmentors_workflower:
       logging: true
   

2. Validate BPMN Files Use the Workflower CLI to validate BPMN syntax:

   vendor/bin/workflower validate config/workflows/default/order_processing.bpmn
   

3. Check Process State Inspect active processes via the Workflower service:

   $activeProcesses = $workflower->getActiveProcesses();
   

Extension Points

1. Custom Serializers Create a custom serializer by implementing SerializerInterface and register it as a service:

   services:
       app.custom_serializer:
           class: App\Serializer\CustomSerializer
           tags: ['phpmentors_workflower.serializer']
   

2. Workflow Events Extend workflow behavior by listening to events:

   // Example: Pause a process on a custom event.
   $eventDispatcher->addListener(
       'workflower.activity.executed',
       function (ActivityExecutedEvent $event) {
           if ($event->getActivityName() === 'approve_order') {
               $event->getProcess()->pause();
           }
       }
   );
   

3. Dynamic Process Variables Use Symfony’s parameter bag to pass dynamic variables:

   $workflower->startProcess('order_processing', [
       'order' => $order,
       'user' => $this->getUser(),
   ]);
   

   Access these in BPMN scripts via execution.getVariable('order').