README

Package for convenient usage of Event Driven Microservices communication using Event Backbone (for now only Apache Kafka is supported).

Installation

You can install the package via composer:

composer require vmorozov/event-backbone-laravel

You will have to publish the config file with:

php artisan vendor:publish --tag="event-backbone-laravel-config"

Usage

Producing events

To start producing events you have to create your first event that implements Vmorozov\EventBackboneLaravel\Producer\ExternalEvent interface.

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Vmorozov\EventBackboneLaravel\Producer\ExternalEvent;

class UserCreated implements ExternalEvent
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    private User $user;

    public function __construct(User $user)
    {
        $this->user = $user;
    }

    public function getTopic(): string
    {
        return 'users';
    }

    public function getName(): string
    {
        return 'user_created';
    }

    public function getKey(): string
    {
        return $this->user->getKey();
    }

    public function getPayload()
    {
        return $this->user->toJson();
    }

    public function getHeaders(): array
    {
        return [];
    }
}

Then you have to fire event created in previous step.

use App\Events\UserCreated;

// some code here
event(new UserCreated($user));

Consuming events

To start consuming events you have to create your first event that implements Vmorozov\EventBackboneLaravel\Consumer\ExternalConsumedEvent interface and create Laravel Event Listener for it.
Here is the example for consuming event produced in "Producing events" section.
Create event:

<?php

namespace App\Events;

use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Vmorozov\EventBackboneLaravel\Consumer\ExternalConsumedEvent;

class UserCreatedConsumedEvent implements ExternalConsumedEvent
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    private array $payload;

    public function __construct(array $payload)
    {
        $this->payload = $payload;
    }

    public function getId()
    {
        return $this->payload['id'];
    }

    public function getName(): string
    {
        return $this->payload['name'];
    }

    public function getEmail(): string
    {
        return $this->payload['email'];
    }
}

Create listener:

<?php

namespace App\Listeners;

use App\Events\UserCreatedConsumedEvent;
use App\Models\User;
use Illuminate\Contracts\Queue\ShouldQueue;

class UserCreatedListener implements ShouldQueue
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  object  $event
     * @return void
     */
    public function handle(UserCreatedConsumedEvent $event): void
    {
        if (User::query()->find($event->getId())) {
            return;
        }

        User::unguard();
        User::query()->create([
            'id' => $event->getId(),
            'name' => $event->getName(),
            'email' => $event->getEmail(),
        ]);
    }
}

Register your listener in EventServiceProvider:

protected $listen = [
    \App\Events\UserCreatedConsumedEvent::class => [
        \App\Listeners\UserCreatedListener::class,
    ],
];

To start consuming events run following artisan command:

php artisan event_backbone:consume

Configuration

Context feature

Events can contain additional context to enable switching app state on receiving events. To Enable this feature you have to add two classes somewhere in your application: ContextProvider and Context applier and register them in config.

1. Create applier class:

<?php

namespace App\Utils\EventBackbone;

use Vmorozov\EventBackboneLaravel\Producer\Context\ProducedEventContextProvider;
use Vmorozov\LaravelFluentdLogger\Tracing\TraceStorage;

class ContextProvider implements ProducedEventContextProvider
{
    private TraceStorage $traceStorage;

    public function __construct(TraceStorage $traceStorage)
    {
        $this->traceStorage = $traceStorage;
    }

    public function getContext(): array
    {
        return [
            'trace_id' => $this->traceStorage->getTraceId(),
        ];
    }
}

1. Create context applier class:

<?php

namespace App\Utils\EventBackbone;

use Vmorozov\EventBackboneLaravel\Consumer\Context\ConsumedEventContextApplier;
use Vmorozov\LaravelFluentdLogger\Tracing\TraceStorage;

class ContextApplier implements ConsumedEventContextApplier
{
    private TraceStorage $traceStorage;

    public function __construct(TraceStorage $traceStorage)
    {
        $this->traceStorage = $traceStorage;
    }

    public function apply(array $context): void
    {
        $this->traceStorage->setTraceId($context['trace_id']);
    }
}

1. Register created classes in event-backbone-laravel.php config:

'context' => [
    'provider_class' => \App\Utils\EventBackbone\ContextProvider::class,
    'applier_class' => \App\Utils\EventBackbone\ContextApplier::class,
],

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Vladimir Morozov
• All Contributors

License

The MIT License (MIT). Please see License File for more information.