Download the PHP package neunerlei/event-bus without Composer

Event Bus

This package contains a PSR-14 compliant event dispatcher facade, which aims to bring the listener provider and dispatcher objects closer together.

While I see where PSR is coming from, for the most part in my daily life it feels weired to have the registration of listeners and dispatching of events in two different classes. This is were this facade comes in; it combines both the dispatcher and provider into a single class you can use in your code.

Version 2.0

The second version does no longer rely on the Tukio library, instead provides it's own listener provider and dispatcher implementations. The dependency on my Options library has also been removed in order to improve performance in event-heavy projects.

Installation

Install this package using composer:

Basic usage

You can use the event bus like any other good'ol event bus implementation you have without psr 14.

Using listener priorities

You can set a priority for a registered listener that defines the order in which they are executed. Priorities can be set to any integer value, where 0 is the default. The value on the "+" range defines a priority higher (earlier) than default, on the "-" range defines a lower (later) priority instead.

Using id based ordering

The library provides "id"-based ordering, meaning you can provide Ids to your listeners and order other listeners before/after said id. The Event Bus also provides a facade for that.

One time only events

Since version 3.0.0 it is possible to register one time only listeners. Meaning the listener will automatically be removed from the list after it was executed once. This feature works with all used listener providers out of the box.

Using event subscribers

The concept of event subscribers is a concept that was (correct me if I'm wrong) mostly pushed by Symfony. It provides you with a unified solution for having multiple listeners in a single service.

The bus provides you with two options on how to register event subscribers.

Option 1: Existing instance

This option is the way to go if you already have the instance of a subscriber. The subscriber class has to implement the interface to be valid.

Option 2: Lazy instantiation

The second option is used to register a service lazily. This means that you don't have to provide the instance of your subscriber, but pass the name of the class to the event bus. In that case the instance will only be created if one of the subscribed events was dispatched.

To create the instance lazily you can provide a factory function (the example below), that should return the instance of the subscriber. The other method of creating a service instance is to use a PSR-11 Container object that should be passed into the constructor of the event bus. If the event bus has a container implementation the factory definition is optional.

Altering the concrete dispatcher, listener provider and container

As stated above we use our own Dispatcher and ListenerProvider implementations internally to provide the main logic of the bus. However the event bus class is designed to be agnostic to the PSR-14 implementation you want to use.

You may override the internal container, the listener provider and the dispatcher object by using the API:

Listener provider adapter

One problem I encountered while writing the facade was, that PSR-14 does not define a unified contract for adding listeners (which is in fact one of it's strengths). For that reason we have to provide an adapter that translates the registration to the correct listener provider implementation. An adapter can be registered on a class or interface base and can be any callable. The example below shows a dummy implementation of the already builtin adapter to the Tukio library by Larry Garfield.

To use the library install it using composer:

After that you can register the provider adapter like so: IMPORTANT: This is an example on how to implement your own adapter, you don't have to do this for the crell/tukio implementation!

The adapter receives four parameters.

• $provider is the instance of the concrete provider implementation
• $event is the class of a single event the given $listener should be bound to
• $item the prepared configuration object for the event listener to register. Contains the parsed default options.
• $options the raw $options array that was passed, you can implement the option validation on your needs.

one time events (once) If your listener provider supports one time events, basically "once" in frontend applications, you can set the third parameter of setProviderAdapter() to true, meaning your provider will handle such events internally. Otherwise the event bus will automatically use a fallback using our internal ListenerProviderOnceProxy.

Please keep in mind, if you tell the event bus that your provider handles "once", your adapter must translate that feature to your actual provider. This could look like this:

Usage as PSR-14 Dispatcher and/or Listener Provider

The event bus class implements the EventDispatcherInterface as well as the ListenerProviderInterface. That way you can use the bus instance as an aggregate for any other PSR-14 compatible project without issues.

StoppableEvents

PSR-14 defines how stoppable events should be handled, so we provide an abstract for that use case. If you want to create an event which is stoppable simply extend the class. Or if you extend an existing event you may use the as well.

Special Thanks

Special thanks goes to the folks at LABOR.digital (which is the word german for laboratory and not the english "work" :D) for making it possible to publish my code online.

Postcardware

You're free to use this package, but if it makes it to your production environment I highly appreciate you sending me a postcard from your hometown, mentioning which of our package(s) you are using.

You can find my address here.

Thank you :D