The Biurad PHP Events Bus

biurad/php-events-bus is an events dispatcher for PHP 7.2+ based on The Symfony EventDispatcher, created by Fabien Potencier. which provides tools that allow your application components to communicate with each other by dispatching events and listening to them.

The Symfony EventDispatcher component implements the Mediator and Observer design patterns to make all these things possible and to make your projects truly extensible. This package adds a touch of PSR-11 container, removes The Symfony Stopwatch component from traceable events, and adds a minor performance gain.

📦 Installation & Basic Usage

This project requires PHP 7.2 or higher. The recommended way to install, is via Composer. Simply run:

$ composer require biurad/events-bus

The dispatcher is the central object of the event dispatcher system. In general, a single dispatcher is created, which maintains a registry of listeners. When an event is dispatched via the dispatcher, it notifies all listeners registered with that event. In addition to registering listeners with existing events, you can create and dispatch your own events. This is useful feature by symfony to keep different components of your own system flexible and decoupled:

use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

The lazy event dispatcher can be used to PSR-11 container autowiring for listeners called on events, you can add The DivineNii PHP Invoker library's class instance DivineNii\Invoker\Invoker, injecting optional callable resolvers and a PSR-11 container complaint instance.

use Biurad\Events\LazyEventDispatcher;

$dispatcher = new LazyEventDispatcher();

To take advantage of an existing event, you need to connect a listener to the dispatcher so that it can be notified when the event is dispatched. A call to the dispatcher's addListener() method associates any valid PHP callable to an event:

use Symfony\Contracts\EventDispatcher\Event;

$listener = new AcmeListener();

$dispatcher->addListener('acme.foo.action', [$listener, 'onFooAction']);

// or

$dispatcher->addListener('acme.foo.action', function (Event $event) {
    // will be executed when the acme.foo.action event is dispatched
});

Once a listener is registered with the dispatcher, it waits until the event is notified. In the above example, when the acme.foo.action event is dispatched, the dispatcher calls the given listener method or closure and passes the Event object as the single argument.

The Traceable EventDispatcher is an event dispatcher that wraps any other event dispatcher and can then be used to determine which event listeners have been called by the dispatcher. Pass the event dispatcher to be wrapped and an instance of the PSR-3 logger to its constructor:

use Biurad\Events\TraceableEventDispatcher;
use Psr\Log\NullLogger;

// the event dispatcher to debug
$dispatcher = ...;

$traceableEventDispatcher = new TraceableEventDispatcher($dispatcher, new NullLogger());

After your application has been processed, you can use the getCalledListeners() method to retrieve an array of event listeners that have been called in your application. Similarly, the getNotCalledListeners() method returns an array of event listeners that have not been called:

// ...

$calledListeners = $traceableEventDispatcher->getCalledListeners();
$notCalledListeners = $traceableEventDispatcher->getNotCalledListeners();

📓 Documentation

To have more of documentation, I advice you check out The Symfony EventDispatcher component documentation provided on Symfony website.

⏫ Upgrading

Information on how to upgrade to newer versions of this library can be found in the UPGRADE.

🏷️ Changelog

SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase; See CHANGELOG for more information on what has changed recently.

Any classes or methods marked @internal are not intended for use outside of this library and are subject to breaking changes at any time, so please avoid using them.

🛠️ Maintenance & Support

When a new major version is released (1.0, 2.0, etc), the previous one (0.19.x) will receive bug fixes for at least 3 months and security updates for 6 months after that new release comes out.

(This policy may change in the future and exceptions may be made on a case-by-case basis.)

Professional support, including notification of new releases and security updates, is available at Biurad Commits.

👷‍♀️ Contributing

To report a security vulnerability, please use the Biurad Security. We will coordinate the fix and eventually commit the solution in this project.

Contributions to this library are welcome, especially ones that:

• Improve usability or flexibility without compromising our ability to adhere to Mediator and Observer design patterns.
• Optimize performance
• Fix issues with adhering to this package.

Please see CONTRIBUTING for additional details.

🧪 Testing

$ composer test

This will tests biurad/events-bus will run against PHP 7.2 version or higher.

👥 Credits & Acknowledgements

• Divine Niiquaye Ibok
• All Contributors

🙌 Sponsors

Are you interested in sponsoring development of this project? Reach out and support us on Patreon or see https://biurad.com/sponsor for a list of ways to contribute.

📄 License

biurad/php-events-bus is licensed under the BSD-3 license. See the LICENSE file for more details.

🏛️ Governance

This project is primarily maintained by Divine Niiquaye Ibok. Members of the Biurad Lap Leadership Team may occasionally assist with some of these duties.

🗺️ Who Uses It?

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us an email or message mentioning this library. We publish all received request's at https://patreons.biurad.com.

Check out the other cool things people are doing with biurad/php-events-bus: https://packagist.org/packages/biurad/events-bus/dependents