Flow Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ejm/flow-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Estevejm\FlowBundle\FlowBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference Estevejm\FlowBundle\Configuration
   

   Or manually define in config/packages/estevejm_flow.yaml:

   estevejm_flow:
       bus: 'your_message_bus_service_id'  # e.g., 'symfony_bus.message_bus'
       visualizer: 'estevejm_flow.visualizer'
   

3. First Use Case Inject the Flow service in a controller or command:

   use Estevejm\FlowBundle\Flow\Flow;
   
   class MessageController extends AbstractController
   {
       public function __construct(private Flow $flow) {}
   
       public function index()
       {
           $this->flow->track('event_name', ['data' => 'payload']);
           $flowData = $this->flow->getFlowData();
           return $this->render('flow/visualize.html.twig', ['flow' => $flowData]);
       }
   }
   

Implementation Patterns

Core Workflow

1. Tracking Messages Use Flow::track() to log messages with metadata:

   $this->flow->track('user.created', [
       'user_id' => 123,
       'timestamp' => now(),
   ]);
   

2. Visualization Render the flow graph in Twig:

   {% include 'EstevejmFlowBundle::visualizer.html.twig' with {
       'flowData': flow
   } %}
   

   Customize the visualizer by extending the base template or overriding the estevejm_flow.visualizer service.

3. Integration with Message Bus Decorate your bus service to auto-track messages:

   # config/services.yaml
   Estevejm\FlowBundle\Flow\Bus\FlowBusDecorator:
       decorates: 'symfony_bus.message_bus'
       arguments:
           $bus: '@.inner'
           $flow: '@estevejm_flow.flow'
   

4. Command-Line Usage Dump flow data to a file:

   php bin/console estevejm:flow:dump --output=flow_data.json
   

Advanced Patterns

• Conditional Tracking Use middleware to filter tracked messages:

  $this->flow->trackIf(
      'user.login',
      ['ip' => $request->ip()],
      fn () => auth()->check()
  );
  

• Custom Visualizers Extend the FlowVisualizer class to support alternative formats (e.g., DOT, GraphQL):

  class CustomVisualizer extends FlowVisualizer
  {
      public function visualize(array $flowData): string
      {
          // Custom logic
      }
  }
  

• Storage Backends Replace the default in-memory storage with a database or cache:

  estevejm_flow:
      storage: 'estevejm_flow.storage.doctrine'
  

Gotchas and Tips

Common Pitfalls

1. Performance Overhead

   • Tracking every message may impact performance. Use trackIf() or middleware to filter.
   • Clear flow data periodically:

     php bin/console estevejm:flow:clear
     

2. Visualizer Dependencies

   • The default visualizer relies on JavaScript libraries (e.g., D3.js). Ensure they’re loaded in your Twig template:

     {{ include('EstevejmFlowBundle::scripts.html.twig') }}
     

3. Thread Safety

   • The bundle is not thread-safe by default. For async workers, use a shared storage (e.g., Redis):

     estevejm_flow:
         storage: 'estevejm_flow.storage.redis'
     

4. Message Bus Compatibility

   • Ensure your bus service is properly decorated. Test with:

     $this->assertInstanceOf(FlowBusDecorator::class, $this->bus);
     

Debugging Tips

• Enable Debug Mode Add to config/packages/estevejm_flow.yaml:

  estevejm_flow:
      debug: true
  

  This logs raw flow data to the Symfony profiler.

• Inspect Flow Data Dump the raw data for debugging:

  dd($this->flow->getFlowData());
  

Extension Points

1. Custom Storage Implement Estevejm\FlowBundle\Storage\StorageInterface:

   class DatabaseStorage implements StorageInterface
   {
       public function save(array $data): void
       {
           // Save to DB
       }
   
       public function load(): array
       {
           // Load from DB
       }
   }
   

   Register it in services.yaml:

   Estevejm\FlowBundle\Storage\DatabaseStorage: ~
   estevejm_flow.storage: '@Estevejm\FlowBundle\Storage\DatabaseStorage'
   

2. Event Listeners Subscribe to flow events (e.g., FlowEvent):

   use Estevejm\FlowBundle\Event\FlowEvent;
   
   class FlowLogger
   {
       public function onFlowUpdated(FlowEvent $event)
       {
           // Log or process flow updates
       }
   }
   

   Bind in services.yaml:

   Estevejm\FlowBundle\EventListener\FlowLogger:
       tags:
           - { name: 'kernel.event_listener', event: 'estevejm.flow.updated', method: 'onFlowUpdated' }
   

3. Override Visualizer Create a custom visualizer service:

   services:
       App\Flow\CustomVisualizer:
           arguments:
               $template: '@twig'
           tags:
               - { name: 'estevejm_flow.visualizer', priority: 100 }