PHPackages                             mattferris/events - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mattferris/events

ActiveLibrary[Utility & Helpers](/categories/utility)

mattferris/events
=================

An event dispatcher

0.4(9y ago)03833BSD-2-ClausePHP

Since May 4Pushed 9y ago1 watchersCompare

[ Source](https://github.com/mattferris/events)[ Packagist](https://packagist.org/packages/mattferris/events)[ RSS](/packages/mattferris-events/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (6)Used By (3)

events
======

[](#events)

[![Build Status](https://camo.githubusercontent.com/38911c32276c4fe8b451341cd0632322fe894655ace2fa4bef37e4f7cf6a04da/68747470733a2f2f7472617669732d63692e6f72672f6d6174746665727269732f6576656e74732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/mattferris/events)[![SensioLabsInsight](https://camo.githubusercontent.com/3d16521ced7c57b5567024f3b253ab365482d77bdd2e7f93825570dcf3445adf/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f37323530376464372d303630362d346263342d396135622d3633373132323833653033312f6d696e692e706e67)](https://insight.sensiolabs.com/projects/72507dd7-0606-4bc4-9a5b-63712283e031)

This is an events library with an included event logger. It's built with [Udi Dahan's Domain Events pattern](http://www.udidahan.com/2008/08/25/domain-events-take-2/)in mind.

Event Handling
--------------

[](#event-handling)

Implementation starts with creating a `DomainEvents` class in your domain that extends `MattFerris\Events\AbstractDomainEvents`.

```
namespace MyDomain;

class DomainEvents extends \MattFerris\Events\AbstractDomainEvents
{
}
```

Then you can create individual event classes either by extending `MattFerris\Events\Event` or implementing `MattFerris\Events\EventInterface`. `Event` is an empty class so your event class will still need to provide it's own logic.

```
namespace MyDomain;

class SomeEvent extends MattFerris\Events\Event
{
    protected $someArgument;

    public function __construct($someArgument)
    {
        $this->someArgument = $someArgument;
    }

    public function getSomeArgument()
    {
        return $this->someArgument;
    }
}
```

To raise/dispatch an event from within your domain entities, call `DomainEvents::dispatch()`.

```
namespace MyDomain;

class SomeEntity
{
    public function doSomething()
    {
        // stuff happens

        // dispatch event
        DomainEvents::dispatch(new SomeEvent($argument));
    }
}
```

At the moment, there is no dispatcher configured so the event won't be handled by anything. Configuring a dispatcher can be done like so:

```
$dispatcher = new MattFerris\Events\Dispatcher();
MyDomain\DomainEvents::setDispatcher($dispatcher);
```

And now you can add events listeners to the dispatcher. Listeners can be any `callable`, and can listen for a specific event or pattern matched event. To match a specific event, use the fully qualified class name.

```
$dispatcher->addListener('MyDomain.SomeEvent', function ($event) { ... });
```

It's also possible to listen for events based on a prefix or suffix.

```
// listen for all events in the `MyDomain` namespace
$dispatcher->addListener('MyDomain.', $handler);

// listen for all SomeEvent events in any domain
$dispatcher->addListener('.SomeEvent', $handler);
```

Finally, you can listen for all events using an asterisk.

```
// listen for all events
$dispatcher->addListener('*', $handler);
```

Event Names
-----------

[](#event-names)

For flexiblity, listeners can also be assigned to listen for arbitrary event names. An event name can be passed to the dispatch method when the event is dispatched.

```
$dispatcher->addListener('foo.bar', $listener);

$dispatcher->dispatch($event, 'foo.bar');
```

Listener Priority
-----------------

[](#listener-priority)

By default, all listeners are given the same priority, and are called based on the order they were added. Listeners can also be assigned a priority to ensure they are called sooner or later then other listeners. The priority is an integer that is passed when adding the listener. `0` is the highest priority.

```
// give the listener the highest priority
$dispatcher->addListener('*', $listener, 0);
```

Priorities can also be assigned using the priority constants:

- `PRIORITY_HIGH` = 0
- `PRIORITY_NORMAL` = 50
- `PRIORITY_LOW` = 100

```
// alternatively, you can use the priority constant
$dispatcher->addListener('*', $listener, Dispatcher::PRIORITY_HIGH);
```

Event Providers
---------------

[](#event-providers)

Events can be added using providers. Simply create a class that implements `MattFerris\Provider\ProviderInterface` and create a method called `provides()`. When passed to the `register()` method on the dispatcher, the `provides()`method will be passed an instance of the dispatcher, and you can then add listeners.

```
use MattFerris\Provider\ProviderInterface;
use MattFerris\Provider\ConsumerInterface;

class EventProvider implements ProviderInterface
{
    public function provides(ConsumerInterface $dispatcher)
    {
        $dispatcher->addListener('*', $listener);
        ...
    }
}
```

Event Logging
-------------

[](#event-logging)

Event logging is accomplished by using `MattFerris\Events\Logger`. The constructor takes an instance of `Dispatcher` and a callable that is passed the resulting log message and can then write it to a log file, stderr, etc.

```
$logger = new MattFerris\Events\Logger($dispatcher, function ($msg) { error_log($msg); });
```

That's it! All dispatched events will be logged to PHP's error log. By default, log messages are just the name of the event prefixed with `event: `. For example:

```
event: MattFerris\Events\Event

```

You can change the prefix using `setPrefix()`.

```
$logger->setPrefix('another prefix: ');
```

You can use logging helpers to customize the messages for certain events. Create a class in your domain called `DomainEventLoggerHelpers` and have it extend `MattFerris\Events\AbstractDomainEventLoggerHelpers`. Then simply create static methods to be called for domain events, where each method returns the string to be logged. These methods should start with `on` followed by the event name e.g. `onSomeEvent`.

```
namespace MyDomain;

class DomainEventLoggerHelpers extends MattFerris\Events\AbstractDomainEventLoggerHelpers
{
    static public function onSomeEvent(SomeEvent $e)
    {
        $foo = $e->getFoo();
        $bar = $e->getBar();

        return "SomeEvent was dispatched with values foo=$foo, bar=$bar";
    }
}
```

To register the helpers with the logger:

```
MyDomain\DomainEventLoggerHelepers::addHelpers($logger);
```

Now, when `SomeEvent` is dispatched, the above helper will be called and the returned string will be logged.

```
event: SomeEvent was dispatched with values foo=blah, bar=bleh

```

In my opinion, it makes sense to have these logging helpers defined in `MyDomain\DomainEventLoggerHelpers` as the helpers are directly related to the events in the domain. When domain events are updated, the logging helpers can be updated and committed all together.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~204 days

Total

4

Last Release

3420d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9d3d46e7fdc93a3d67119773bdae779e281a87f2d70e95568a969c72205aedf7?d=identicon)[mattferris](/maintainers/mattferris)

---

Top Contributors

[![mattferris](https://avatars.githubusercontent.com/u/1687325?v=4)](https://github.com/mattferris "mattferris (16 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mattferris-events/health.svg)

```
[![Health](https://phpackages.com/badges/mattferris-events/health.svg)](https://phpackages.com/packages/mattferris-events)
```

###  Alternatives

[symfony/event-dispatcher-contracts

Generic abstractions related to dispatching event

3.4k756.5M424](/packages/symfony-event-dispatcher-contracts)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)