README

The RabbitEvents Publisher component provides an API for publishing events across the application structure. More information is available in the Nuwber's RabbitEvents documentation.

The RabbitEvents Publisher is the part that informs all other microservices that a payment has succeeded.

Table of Contents

1. Installation via Composer
2. Configuration
3. Publishing
4. Testing

Installation via Composer

RabbitEvents Publisher can be installed via the Composer package manager:

composer require rabbitevents/publisher

After installing Publisher, you can execute the rabbitevents:install Artisan command, which will install the RabbitEvents configuration file into your application:

php artisan rabbitevents:install

Configuration

Details about the configuration are described in the library documentation.

Publishing

Using an Event class

Here is an example event class:

<?php

use App\Payment;
use App\User;
use RabbitEvents\Publisher\ShouldPublish;
use RabbitEvents\Publisher\Support\Publishable;

class PaymentSucceededRabbitEvent implements ShouldPublish
{
    use Publishable;

    public function __construct(private User $user, private Payment $payment)
    {
    }

    public function publishEventKey(): string
    {
        return 'payment.succeeded';
    }

    public function toPublish(): mixed
    {
        return [
            'user' => $this->user->toArray(),
            'payment' => $this->payment->toArray(),
        ];
    }
}

The only requirement for event classes is to implement the \RabbitEvents\Publisher\ShouldPublish interface.

As an alternative, you could extend \RabbitEvents\Publisher\Support\AbstractPublishableEvent. This class was created to simplify the creation of event classes.

To publish this event, you just need to call the publish method of the event class and pass all the necessary data:

<?php

$payment = new Payment(...);

// ...

PaymentSucceededRabbitEvent::publish($request->user(), $payment);

The method publish is provided by the trait Publishable.

Using the publish function

Sometimes, it is easier to use the helper function publish with an event key and payload:

<?php

publish(
    'payment.succeeded',
    [
        'user' => $request->user()->toArray(),
        'payment' => $payment->toArray(),
    ]
);

Publish an Event object with the publish function

You can also use a combination of the two previous methods:

<?php

$event = new PaymentSucceededEvent($request->user(), $payment);

event($event)
publish($event);

Publishing Protobuf Messages

You can publish Google Protobuf messages. The system will automatically handle serialization and set the content_type to application/x-protobuf.

Note: You must install the rabbitevents/protobuf package to use this feature.

use App\Messages\AccountCreated; // Generated Protobuf class

$message = new AccountCreated(['id' => 123, 'name' => 'John']);

publish('account.created', $message);

The type header will be automatically set to App\Messages\AccountCreated, allowing the consumer to re-hydrate the object.

Testing

We always write tests. Tests in our applications contain many mocks and fakes to test how events are published.

There is the PublishableEventTesting trait that provides assertion methods in an Event class that you want to test.

Event.php

<?php

namespace App\BroadcastEvents;

use RabbitEvents\Publisher\ShouldPublish;
use RabbitEvents\Publisher\Support\Publishable;
use RabbitEvents\Publisher\Support\PublishableEventTesting;

class Event implements ShouldPublish
{
    use Publishable;
    use PublishableEventTesting;

    public function __construct(private array $payload) 
    {
    }

    public function publishEventKey(): string
    {
        return 'something.happened';
    }

    public function toPublish(): array
    {
        return $this->payload;
    }
}

Test.php

<?php

use \App\RabbitEvents\Event;
use \App\RabbitEvents\AnotherEvent;

Event::fake();

$payload = [
    'key1' => 'value1',
    'key2' => 'value2',
];

Event::publish($payload);

Event::assertPublished('something.happened', $payload);

AnotherEvent::assertNotPublished();

If the assertion does not pass, Mockery\Exception\InvalidCountException will be thrown.
Don't forget to call \Mockery::close() in tearDown or similar methods of your tests.