Laravel Protobuf Events

Helper to allow nuwber/rabbitevents to work with protobuf

Requirements

• PHP >= 8.5
• Laravel 12.x

Main features

• Allow to publish/listen protobuf messages using nuwber/rabbit-events easily.

Installation

You can require the last version of the package using composer

composer require softonic/laravel-protobuf-events

Configuration

First you need to configure the nuwber/rabbit-events package to be able to use the package.

Then you must configure config/protobuf-events.php to set the client of the library. This client allows to isolate different services, identifying the origin of the message.

Configuring a listener

In the RabbitEventsServiceProvider::boot() register the listeners that you want using the ExternalEvents::decorateListener() method.

    /**
     * Register any events for your application.
     */
    public function boot(): void
    {
        $this->listen = [
            'my.routing.key' => [
                ExternalEvents::decorateListener(MyListener::class),
            ],
        ];

        parent::boot();
    }

The listener needs a method called handle() that will receive the message and the routing key, and a method called setClient() to identify the origin of the message.

class MyListener
{
    public function setClient(string $client): void
    {
        // ...
    }
    public function handle(ProtobufExampleMessage $event): void
    {
        // ...
    }
}

Publishing messages

To publish a message, you need to use the ExternalEvents::publish() method.

ExternalEvents::publish(
    ':service:',
    (new ProtobufExampleMessage)
        ->setName('My name')
        ->setAge(10)
);

Advanced usage

Sometimes you need to use the package in a different way than the default. For example, you can use the package to decode a message from a string. In that case, you are able to decode the message using the ExternalEvents::decode() method.

$message = ExternalEvents::decode(
    ProtobufExampleMessage::class,
    '\n My name\n 10\n' // The message is a string with the protobuf message.
);

Logging protobuf messages

If you want to log the outgoing protobuf messages and the incoming ones, you can configure a logger and a formatter for the message to be logged. For that purpose you have the methods ExternalEvents::setLogger() and ExternalEvents::setFormatter(). The logger must implement the Psr\Log\LoggerInterface and the formatter, the LogMessageFormatterInterface interface.

ExternalEvents::setLogger(Log:getFacadeRoot());
ExternalEvents::setFormatter(new ProtobufLogMessageFormatter());

The formatter will have two methods, formatOutgoingMessage() and formatIncomingMessage(), that will be called when a message is sent or received, respectively. Both should return a LogMessage object, which contains the message to log and the context.

The log level can be changed by setting the communications_log_level key in config/protobuf-events.php.

Testing

softonic/laravel-protobuf-events has a PHPUnit test suite, and a coding style compliance test suite using PHP CS Fixer.

To run the tests, run the following command from the project folder.

docker compose run --rm test

To run PHPUnit only:

docker compose run --rm phpunit

To check code style:

docker compose run --rm php composer run checkstyle

To fix code style issues:

docker compose run --rm fixcs

To run static analysis:

docker compose run --rm phpstan

To open a terminal in the dev environment:

docker compose run --rm php sh

License

The Apache 2.0 license. Please see LICENSE for more information.