Php Messaging Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require event-engine/php-messaging
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       EventEngine\Messaging\MessagingServiceProvider::class,
   ],
   

2. Publish Config

   php artisan vendor:publish --provider="EventEngine\Messaging\MessagingServiceProvider"
   

   Configure config/messaging.php with your broker (e.g., RabbitMQ, Redis, or SQS).

3. First Use Case: Sending a Message

   use EventEngine\Messaging\Message;
   
   // Define a message
   $message = new Message('user.created', [
       'user_id' => 123,
       'email' => 'user@example.com'
   ]);
   
   // Send via the facade (or container)
   \Messaging::send($message);
   

4. Consuming Messages Create a listener class:

   namespace App\Listeners;
   
   use EventEngine\Messaging\Message;
   use EventEngine\Messaging\Contracts\MessageListener;
   
   class HandleUserCreated implements MessageListener
   {
       public function handle(Message $message)
       {
           // Process the message
           logger()->info('User created:', $message->payload());
       }
   }
   

   Register it in config/messaging.php under listeners.

Implementation Patterns

Core Workflows

1. Message Dispatching

   • Facade Usage: Prefer \Messaging::send() for simplicity.
   • Queue Jobs: For async processing, wrap in a job:

     use EventEngine\Messaging\Jobs\SendMessage;
     
     SendMessage::dispatch($message);
     

   • Batch Processing:

     \Messaging::sendBatch([
         new Message('order.processed', ['order_id' => 1]),
         new Message('notification.send', ['user_id' => 1]),
     ]);
     

2. Listener Registration

   • Dynamic Binding: Bind listeners dynamically in a service provider:

     $this->app->bind(MessageListener::class, function ($app) {
         return new HandleUserCreated();
     });
     

   • Priority Handling: Use the priority key in config/messaging.php to order listeners.

3. Message Serialization

   • Default: JSON. Override in config/messaging.php:

     'serializer' => \Symfony\Component\Serializer\Serializer::class,
     

   • Custom serializers must implement EventEngine\Messaging\Contracts\MessageSerializer.

4. Error Handling

   • Retry Logic: Configure retries in config/messaging.php:

     'retry' => [
         'max_attempts' => 3,
         'delay' => 1000, // ms
     ],
     

   • Dead Letter Queues: Enable via:

     'dead_letter' => [
         'enabled' => true,
         'queue' => 'dead-letters',
     ],
     

5. Integration with Laravel Events

   • Bridge Laravel events to messages in an event listener:

     public function handle(UserCreated $event)
     {
         \Messaging::send(new Message('user.created', $event->toArray()));
     }
     

Gotchas and Tips

Common Pitfalls

1. Broker Connection Issues

   • Symptom: Messages disappear or listeners fail silently.
   • Fix: Verify broker credentials in config/messaging.php and check broker health (e.g., rabbitmqctl status for RabbitMQ).
   • Debug: Enable logging in the config:

     'log' => [
         'enabled' => true,
         'channel' => 'single',
     ],
     

2. Listener Not Triggered

   • Cause: Missing registration in config/messaging.php or incorrect message topic.
   • Tip: Use the topic method to explicitly bind listeners:

     \Messaging::listen('user.created', HandleUserCreated::class);
     

3. Serialization Errors

   • Symptom: Message payload must be JSON serializable.
   • Fix: Ensure payloads are arrays or implement JsonSerializable:

     $message = new Message('event.name', json_serializable_object());
     

4. Race Conditions

   • Issue: Duplicate message processing.
   • Solution: Use message IDs and idempotency checks in listeners:

     if ($message->id() && $this->alreadyProcessed($message->id())) {
         return;
     }
     

5. Performance Bottlenecks

   • Tip: Batch small messages to reduce overhead:

     \Messaging::sendBatch(array_map(fn ($user) => new Message('user.updated', ['id' => $user->id]), $users));
     

Advanced Tips

1. Custom Broker Adapters

   • Extend EventEngine\Messaging\Contracts\Broker to support unsupported brokers (e.g., Kafka):

     class KafkaBroker implements Broker
     {
         public function publish(Message $message) { /* ... */ }
         public function consume(callable $callback) { /* ... */ }
     }
     

   • Register via the service provider.

2. Message Middleware

   • Add middleware to transform messages before/after processing:

     \Messaging::extend('kafka', function ($app) {
         return new KafkaBroker($app['kafka']);
     });
     

3. Testing

   • Mock the broker in tests:

     $this->app->instance(Broker::class, new MockBroker());
     

   • Use the MessagingTestCase trait for assertions:

     use EventEngine\Messaging\Testing\MessagingTestCase;
     
     class MyTest extends MessagingTestCase
     {
         public function testMessageSent()
         {
             $this->assertSent('user.created');
         }
     }
     

4. Configuration Quirks

   • Environment Overrides: Use environment variables for broker settings:

     'broker' => env('MESSAGING_BROKER', 'redis'),
     

   • Default Exchange/Queue: Configure in config/messaging.php:

     'defaults' => [
         'exchange' => 'default_exchange',
         'queue' => 'default_queue',
     ],
     

5. Monitoring

   • Track message flow with middleware:

     \Messaging::middleware(function ($message, $next) {
         logger()->info('Message sent:', ['topic' => $message->topic(), 'payload' => $message->payload()]);
         return $next($message);
     });