Flow Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ejm/flow
   

   Ensure estevejm/simplebus is installed (Flow depends on it).

2. Service Provider Register the package in config/app.php under providers:

   Estevejm\Flow\FlowServiceProvider::class,
   

3. Configuration Publish the config file:

   php artisan vendor:publish --provider="Estevejm\Flow\FlowServiceProvider"
   

   Update config/flow.php with your message bus configuration (e.g., RabbitMQ, Redis).

4. First Use Case: Tracking a Message Inject the Flow facade or service into a command/handler:

   use Estevejm\Flow\Facades\Flow;
   
   public function handle()
   {
       Flow::track('user.created', ['user_id' => 123]);
   }
   

Implementation Patterns

Core Workflows

1. Tracking Messages Use Flow::track($messageName, $payload) in:

   • Command handlers (e.g., after processing a UserCreated event).
   • Middleware (to log incoming requests as "messages").
   • Jobs (e.g., UserProcessedJob::dispatch() → Flow::track('user.processed')).

2. Visualizing Flow

   • Use the Flow UI to render graphs.
   • Configure the UI in config/flow.php:

     'ui' => [
         'enabled' => true,
         'port' => 8080,
     ],
     

   • Access the UI at http://localhost:8080 (or your configured port).

3. Integrating with SimpleBus

   • Wrap SimpleBus handlers to auto-track messages:

     public function handle($command)
     {
         Flow::track('command.' . get_class($command), $command->toArray());
         // ... rest of logic
     }
     

4. Customizing Message Metadata Add context to messages for richer visualization:

   Flow::track('order.placed', [
       'order_id' => 456,
       'user_id'  => 123,
       'status'   => 'pending',
   ], [
       'source' => 'api',
       'priority' => 'high',
   ]);
   

Gotchas and Tips

Pitfalls

1. Message Naming Collisions

   • Avoid generic names like message.sent. Use namespaces (e.g., user.profile.updated).
   • Override the Flow::getMessageName() method if dynamic naming is needed.

2. Performance Overhead

   • Tracking every message may slow down high-throughput systems.
   • Use Flow::track() sparingly for critical paths or sample messages.

3. UI Configuration Conflicts

   • Ensure flow-ui is installed separately (composer require ejm/flow-ui).
   • Port conflicts may occur if another service uses the same port (default: 8080).

4. SimpleBus Dependency

   • The package assumes SimpleBus is configured. If using a different bus (e.g., Laravel Queues), mock the SimpleBus\Message\Message interface or extend the package.

Debugging Tips

1. Check Logs Enable debug mode in config/flow.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs will appear in storage/logs/flow.log.

2. Verify Message Storage By default, messages are stored in storage/framework/flow. Clear old data with:

   php artisan flow:clear
   

3. UI Not Loading?

   • Ensure the UI service is running:

     php artisan flow:ui
     

   • Check for PHP errors in the terminal or browser console.

Extension Points

1. Custom Storage Override the FlowStorage interface to use a database or external service:

   // config/flow.php
   'storage' => [
       'driver' => 'custom',
       'class'  => App\Services\CustomFlowStorage::class,
   ],
   

2. Message Filters Filter messages before visualization (e.g., exclude debug.*):

   // app/Providers/FlowServiceProvider.php
   public function boot()
   {
       Flow::filter(function ($message) {
           return !str_starts_with($message->name, 'debug.');
       });
   }
   

3. Event Listeners Attach listeners to Flow::messageTracked for post-processing:

   Flow::listen('messageTracked', function ($message) {
       // Send to external monitoring tool
   });