laravel-event-pubsub
An event protocol and implementation over pub/sub for Laravel., (*1)
, (*2)
This package is a wrapper bridging php-event-pubsub into Laravel.
It builds on top of the existing laravel-pubsub package adding support
for publishing and subscribing to events over pub/sub., (*3)
If you aren't familiar with the laravel-pubsub package, it's worth first taking a look at their documentation., (*4)
For Laravel 4 support, use the package https://github.com/Superbalist/laravel4-event-pubsub, (*5)
Installation
composer require superbalist/laravel-event-pubsub
The package has a default configuration which uses the following environment variables., (*6)
PUBSUB_EVENTS_CONNECTION=null
PUBSUB_EVENTS_TRANSLATOR=pubsub.events.translators.simple
PUBSUB_EVENTS_VALIDATOR=null
PUBSUB_EVENTS_THROW_VALIDATION_EXCEPTIONS_ON_DISPATCH=true
If the PUBSUB_EVENTS_CONNECTION environment variable or pubsub_events.default config value is left blank, the
default connection will be taken from the laravel-pubsub package config., (*7)
Register the service provider in app.php, (*8)
'providers' => [
// ...
Superbalist\LaravelEventPubSub\PubSubEventsServiceProvider::class,
]
Register the facade in app.php, (*9)
'aliases' => [
// ...
'PubSubEvents' => Superbalist\LaravelEventPubSub\PubSubEventsFacade::class,
]
To customize the configuration file, publish the package configuration using Artisan., (*10)
php artisan vendor:publish --provider="Superbalist\LaravelEventPubSub\PubSubEventsServiceProvider"
You can then edit the generated config at app/config/pubsub_events.php., (*11)
Usage
Simple Events
A SimpleEvent is an event which takes a name and optional attributes., (*12)
// the pubsub_events.translator config setting should be set to 'pubsub.events.translators.simple'
// get the event manager
$manager = app('pubsub.events');
// dispatch an event
$event = new \Superbalist\EventPubSub\Events\SimpleEvent(
'user.created',
[
'user' => [
'id' => 1456,
'first_name' => 'Joe',
'last_name' => 'Soap',
'email' => 'joe.soap@example.org',
],
]
);
$manager->dispatch('events', $event);
// dispatch multiple events
$events = [
new \Superbalist\EventPubSub\Events\SimpleEvent(
'user.created',
[
'user' => [
// ...
],
]
),
new \Superbalist\EventPubSub\Events\SimpleEvent(
'user.created',
[
'user' => [
// ...
],
]
),
];
$manager->dispatchBatch('events', $events);
// listen for an event
$manager->listen('events', 'user.created', function (\Superbalist\EventPubSub\EventInterface $event) {
var_dump($event->getName());
var_dump($event->getAttribute('user'));
});
// listen for all events on the channel
$manager->listen('events', '*', function (\Superbalist\EventPubSub\EventInterface $event) {
var_dump($event->getName());
});
// all the aboce commands can also be done using the facade
PubSubEvents::dispatch('events', $event);
Topic Events
A TopicEvent is an event which takes a topic, name, version and optional attributes., (*13)
// the pubsub_events.translator config setting should be set to 'pubsub.events.translators.topic'
// get the event manager
$manager = app('pubsub.events');
// dispatch an event
$event = new \Superbalist\EventPubSub\Events\TopicEvent(
'user',
'created',
'1.0',
[
'user' => [
'id' => 1456,
'first_name' => 'Joe',
'last_name' => 'Soap',
'email' => 'joe.soap@example.org',
],
]
);
$manager->dispatch('events', $event);
// listen for an event on a topic
$manager->listen('events', 'user/created', function (\Superbalist\EventPubSub\EventInterface $event) {
// ...
});
// listen for an event on a topic matching the given version
$manager->listen('events', 'user/created/1.0', function (\Superbalist\EventPubSub\EventInterface $event) {
// ...
});
// listen for all events on a topic
$manager->listen('events', 'user/*', function (\Superbalist\EventPubSub\EventInterface $event) {
// ...
});
// listen for all events on the channel
$manager->listen('events', '*', function (\Superbalist\EventPubSub\EventInterface $event) {
// ...
});
Schema Events
A SchemaEvent is an extension of the TopicEvent and takes a schema and optional attributes. The topic, name and
version are derived from the schema., (*14)
The schema must be in the format (protocol)://(......)?/events/(topic)/(channel)/(version).json, (*15)
// the pubsub_events.translator config setting should be set to 'pubsub.events.translators.schema'
// the pubsub_events.validator config setting can be set to 'pubsub.events.validators.json_schema' to take advantage of
// JSON Schema validation on incoming events
// get the event manager
$manager = app('pubsub.events');
// dispatch an event
$event = new \Superbalist\EventPubSub\Events\SchemaEvent(
'http://schemas.my-website.org/events/user/created/1.0.json',
[
'user' => [
'id' => 1456,
'first_name' => 'Joe',
'last_name' => 'Soap',
'email' => 'joe.soap@example.org',
],
]
);
$manager->dispatch('events', $event);
// the listen expressions are the same as those used for TopicEvents.
Error Handling
The library supports error handlers for when event translation fails, listen expression fails and validation fails., (*16)
These are configurable as callables in the translate_fail_handler, listen_expr_fail_handler and validation_fail_handler
config options., (*17)
The config contains default callables which will turn the callbacks into Laravel events., (*18)
You can register listeners in the EventServiceProvider for the following events:, (*19)
\Superbalist\LaravelEventPubSub\Events\TranslationFailureEvent(
$message
)
\Superbalist\LaravelEventPubSub\Events\ListenExprFailureEvent(
\Superbalist\EventPubSub\EventInterface $event,
$expr
)
\Superbalist\LaravelEventPubSub\Events\ValidationFailureEvent(
\Superbalist\EventPubSub\ValidationResult $result
)
Wallogit.com
