superbalist/laravel4-event-pubsub

An event protocol and implementation over pub/sub for Laravel 4

laravel4-event-pubsub

An event protocol and implementation over pub/sub for Laravel 4., _(*1)

, _(*2)

This package is a wrapper bridging php-event-pubsub into Laravel. It builds on top of the existing laravel4-pubsub package adding support for publishing and subscribing to events over pub/sub., _(*3)

If you aren't familiar with the laravel4-pubsub package, it's worth first taking a look at their documentation., _(*4)

For Laravel 5 support, use the package https://github.com/Superbalist/laravel-event-pubsub, _(*5)

Installation

composer require superbalist/laravel4-event-pubsub

The package has a default configuration built-in., _(*6)

To customize the configuration file, publish the package configuration using Artisan., _(*7)

php artisan config:publish superbalist/laravel4-event-pubsub

You can then edit the generated config at app/config/packages/superbalist/laravel4-event-pubsub/config.php., _(*8)

Register the service provider in app.php, _(*9)

'providers' => [
    // ...
    'Superbalist\Laravel4EventPubSub\PubSubEventsServiceProvider',
]

Register the facade in app.php, _(*10)

'aliases' => [
    // ...
    'PubSubEvents' => 'Superbalist\Laravel4EventPubSub\PubSubEventsFacade',
]

Usage

Simple Events

A SimpleEvent is an event which takes a name and optional attributes., _(*11)

// 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., _(*12)

// 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., _(*13)

The schema must be in the format (protocol)://(......)?/events/(topic)/(channel)/(version).json, _(*14)

// 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., _(*15)

These are configurable as callables in the translate_fail_handler, listen_expr_fail_handler and validation_fail_handler config options., _(*16)

The config contains default callables which will turn the callbacks into Laravel events., _(*17)

You can listen for the following to hook into these:, _(*18)

$events = app('events'); // or just use the facade Events

$events->listen('pubsub.events.translation_failure', function ($message) {
    // the message failed to translate into an event
});

$events->listen('pubsub.events.listen_expr_failure', function (\Superbalist\EventPubSub\EventInterface $event, $expr) {
    // the event didn't match the listen expression
    // this isn't really an error, but can be useful for debug
});

$events->listen('pubsub.events.validation_failure', function (\Superbalist\EventPubSub\ValidationResult $result) {
    // the event failed validation
    var_dump($result->errors());
});