Phpflo Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require phpflo/phpflo-bundle --dev
   

   Ensure minimum-stability: dev is set in your composer.json root.

2. Enable the Bundle: Add to config/bundles.php:

   PhpFlo\PhpFloBundle\PhpFloBundle::class => ['all' => true],
   

3. First Component: Create a basic component (e.g., src/Component/HelloWorld.php):

   namespace App\Component;
   
   use PhpFlo\Component;
   
   class HelloWorld extends Component {
       public function __construct() {
           $this->outPorts()->add('greeting', ['type' => 'string']);
           $this->inPorts()->on('data', [$this, 'greet']);
       }
   
       public function greet($data) {
           $this->outPorts()->greeting->send("Hello, {$data}!");
       }
   }
   

4. Register the Component: Add to config/services.yaml:

   services:
       app.hello_world:
           class: App\Component\HelloWorld
           tags:
               - { name: phpflo.component, alias: hello_world }
   

5. Define a Graph: Create config/hello_graph.json:

   {
       "processes": {
           "HelloWorld": { "component": "hello_world" }
       },
       "connections": []
   }
   

6. Run the Flow: In a controller or command:

   $network = $this->get('phpflo.network')->fromFile('hello_graph.json');
   $network->getGraph()->addInitial('hello_graph', 'HelloWorld', 'data', 'Alice');
   $network->run();
   

Implementation Patterns

Workflow: Data Processing Pipeline

1. Component Design:

   • Extend PhpFlo\Component or implement PhpFlo\ComponentInterface.
   • Define inPorts() and outPorts() for input/output channels.
   • Use on() to bind events (e.g., data) to methods.

2. Graph Construction:

   • Static Graphs: Define in JSON files (e.g., config/pipeline.json).

     {
         "processes": {
             "Parser": { "component": "app.parser" },
             "Validator": { "component": "app.validator" },
             "Logger": { "component": "app.logger" }
         },
         "connections": [
             { "src": { "process": "Parser", "port": "out" }, "tgt": { "process": "Validator", "port": "in" } }
         ]
     }
     

   • Dynamic Graphs: Build programmatically:

     $graph = $network->getGraph();
     $graph->addProcess('Parser', 'app.parser');
     $graph->connect('Parser', 'out', 'Validator', 'in');
     

3. Execution:

   • Request-Based: Use phpflo.network (components registered once per request).

     $network = $this->get('phpflo.network')->fromFile('pipeline.json');
     $network->getGraph()->addInitial('pipeline', 'Parser', 'input', $data);
     $network->run();
     

   • Long-Running Processes: Use phpflo.network_di (fresh components per run).

     $network = $this->get('phpflo.network_di')->fromFile('pipeline.json');
     

4. Error Handling:

   • Route errors via error ports:

     {
         "connections": [
             { "src": { "process": "Parser", "port": "error" }, "tgt": { "process": "Logger", "port": "in" } }
         ]
     }
     

5. Reusability:

   • Shared Components: Tag components with phpflo.component for reuse across graphs.
   • Parameterized Components: Inject dependencies via Symfony’s DIC:

     class MyComponent extends Component {
         public function __construct(MyService $service) {
             $this->service = $service;
         }
     }
     

     Register in services.yaml:

     app.my_component:
         arguments: ['@my_service']
         tags: [{ name: phpflo.component, alias: my_component }]
     

Integration Tips

1. Symfony Events: Trigger flows from Symfony events (e.g., kernel.request):

   $eventDispatcher->addListener('kernel.request', function () {
       $network = $this->get('phpflo.network')->fromFile('auth_graph.json');
       $network->getGraph()->addInitial('auth_graph', 'Auth', 'input', $request);
       $network->run();
   });
   

2. Messenger Integration: Use flows to process messages:

   $messageBus->dispatch(new MyMessage($data));
   $network = $this->get('phpflo.network')->fromFile('message_graph.json');
   $network->getGraph()->addInitial('message_graph', 'Handler', 'message', $message);
   

3. Configuration: Load graphs dynamically from config:

   # config/packages/phpflo.yaml
   phpflo:
       default_graph: 'app/config/%kernel.environment%_graph.json'
   

   Access via:

   $graphPath = $this->getParameter('phpflo.default_graph');
   

4. Testing: Mock components for unit tests:

   $mockComponent = $this->createMock(ComponentInterface::class);
   $network = new Network([$mockComponent]);
   

Gotchas and Tips

Pitfalls

1. Component Registration:

   • Issue: Components not found in the graph.

     • Fix: Ensure phpflo.component tag is set with a unique alias.
     • Debug: Check compiled services (var/cache/dev/container.yml) for tagged components.

   • Issue: Duplicate components in phpflo.network.

     • Fix: Use phpflo.network_di for dynamic instantiation or ensure shared: false in services.yaml.

2. Port Mismatches:

   • Issue: Connection errors due to port type mismatches.
     • Fix: Explicitly define port types in components:

       $this->inPorts()->add('input', ['type' => 'array']);
       $this->outPorts()->add('output', ['type' => 'string']);
       

3. Circular Dependencies:

   • Issue: Graphs with circular connections cause infinite loops.
     • Fix: Validate graphs before execution or use PhpFlo\Network::validate().

4. Stability Warnings:

   • Issue: Composer blocks installation due to dev stability.
     • Fix: Set minimum-stability: dev in composer.json or use:

       composer require phpflo/phpflo-bundle --dev --ignore-platform-reqs
       

5. Cache Invalidation:

   • Issue: Changes to components or graphs not reflected.
     • Fix: Clear Symfony cache:

       php bin/console cache:clear
       

Debugging Tips

1. Log Port Activity: Add logging to component methods:

   public function greet($data) {
       $this->logger->info("Greeting: {$data}");
       $this->outPorts()->greeting->send("Hello, {$data}!");
   }
   

2. Graph Visualization: Use PhpFlo\Network::toDot() to generate a graphviz diagram:

   $dot = $network->getGraph()->toDot();
   file_put_contents('graph.dot', $dot);
   

3. Component Introspection: Dump component ports during runtime:

   $component = $network->getGraph()->getProcess('HelloWorld')->getComponent();
   var_dump($component->inPorts(), $component->outPorts());
   

Extension Points

1. Custom Component Registry: Override the default registry to filter or transform components:

   $registry = new ComponentRegistry();
   $registry->addFilter(function ($component) {
       return $component instanceof MyCustomComponent;
   });
   $network = new Network($registry);
   

2. Dynamic Graph Loading: Load graphs from databases or APIs:

   $graphData = $this->fetchGraphFromDatabase();
   $network = $this->get('phpflo.network')->fromArray($graphData);
   

3. Port Validation: Extend PhpFlo\Port to add custom validation:

   class ValidatedPort extends Port {
       public function send($data) {
           if (!is_array($data)) {
               throw new \InvalidArgumentException('Expected array');
           }
           parent::send($data);
       }
   }
   

4. **Event