laravel4-event-pubsub

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

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.

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

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

Installation

composer require superbalist/laravel4-event-pubsub

The package has a default configuration built-in.

To customize the configuration file, publish the package configuration using Artisan.

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.

Register the service provider in app.php

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

Register the facade in app.php

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

Usage

Simple Events

A SimpleEvent is an event which takes a name and optional attributes.

// 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.

// 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.

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

// 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.

These are configurable as callables in the translate_fail_handler, listen_expr_fail_handler and validation_fail_handler config options.

The config contains default callables which will turn the callbacks into Laravel events.

You can listen for the following to hook into these:

$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());
});