PHP Classes
elePHPant
Icontem

PHP Event Dispatcher: Register events and call registered listeners

Recommend this page to a friend!
  Info   View files Documentation   View files View files (40)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2014-06-19 (3 years ago) RSS 2.0 feedNot yet rated by the usersTotal: 532 All time: 5,430 This week: 621Up
Version License PHP version Categories
event-dispatcher 1.0.0MIT/X Consortium ...5.4PHP 5, Language, Design Patterns, Traits
Description Author

This package can register events and call registered listeners.

It can register an event listener by associating a name to a callback function that will be invoked when an event with that name happens.

Event listeners may be registered to handle a group of events defined by a event name pattern.

The event name matching may be defined also by an object that determines if a given event should be handled by the subscribed event handler.

Events are be dispatched by calling the registered event listeners.

Registered event listeners may have an associated priority number so they can be called by the order defined by their priority.

Event listeners callback functions may take parameters that define the context of the event.

Name: Protung Dragos <contact>
Classes: 10 packages by
Country: Germany Germany
Innovation award
Innovation award
Nominee: 3x

Details
EventDispatcher Component
=========================

EventDispatcher implements a lightweight version of the Observer design pattern.

```php
use Wingu\OctopusCore\EventDispatcher\EventDispatcher;
use Wingu\OctopusCore\EventDispatcher\EventInterface;
use Wingu\OctopusCore\EventDispatcher\Event;

$dispatcher = new EventDispatcher();
$dispatcher->on('event_name', function (EventInterface $event) {
    // ...
});

$dispatcher->raiseEvent('event_name', new Event($sender));
```

Listening to events
===================

Events are raised through the EventDispatcher. The easiest way to register listeners to handle events is using the `on()` method:
	
```php
$dispatcher->on($eventName, $callback, $priority)
```

The $eventName can be a specific event name, a wildcard event name or a regular expression to match an event name.

```php
$dispatcher->on('core', function(Event $e){}); // by event name
$dispatcher->on('core.*', function(Event $e){}); // wildcard, match anything after *
$dispatcher->on('core.#.error', function(Event $e){}); // wildcard, match a namespace (core.log.error, core.db.error, etc)
$dispatcher->on('/^core\.(.+)$/', function(Event $e){}); // regex
```

There are other several methods to subscribe to events.
	
```php
// By passing an event name matcher.
$eventNameMatcher = new \Wingu\OctopusCore\EventDispatcher\EventNameMatcher\AllNamesMatcher();
$callback = function (EventInterface $e) {
	// do something ...
};
$dispatcher->subscribe($eventNameMatcher, $callback, $priority); // Will actually subscribe to all events.

// By passing a subscription object.
$eventNameMatcher = new \Wingu\OctopusCore\EventDispatcher\EventNameMatcher\NameMatcher('core.mail');
$callback = function (EventInterface $e) {
	// do something ...
};
$subscription = new \Wingu\OctopusCore\EventDispatcher\Subscription($eventNameMatcher, $callback);
$dispatcher->addSubscription($subscription);
```

To unsubscribe use:

```php
$dispatcher->off($eventNameMatcher, $callback);
$dispatcher->unsubscribe($eventNameMatcher, $callback); // $eventNameMatcher doesn't have to be the same instance, but has to match the same event(s).
$dispatcher->removeSubscription($subscription);
```

When an event is raised the return of each listener is stacked into a ResponseCollectionInterface object.

Raising / dispatching events
============================

Events can be raised / dispatched by calling the `raiseEvent($event)` or `raiseEventUntil($event, $callback)` method. 
The arguments of the event must be an array with the key as the argument name.

```php
$dispatcher = new EventDispatcher();

$args = ['param1' => 1, 'param2' => 2, 'date' => new \Datetime()];
$event = new Event($sender, $args);

$dispatcher->raiseEvent('event_name', $event);
$dispatcher->raiseEventUntil('event_name', $event, function() {
    echo "Event processed!";
});
```

For object instance event dispatching the EventDispatcherTrait trait can be attached to any object and then the API is the same as for the dispatcher.

Tests
=========================

You can run the unit tests with the following command:

    $ cd path/to/Wingu/OctopusCore/EventDispatcher/
    $ composer.phar install --dev
    $ phpunit
  Files folder image Files  
File Role Description
Files folder imagesrc (1 directory)
Files folder imagetests (1 directory)
Accessible without login Plain text file .gitattributes Data
Accessible without login Plain text file .gitignore Data
Accessible without login Plain text file composer.json Data
Accessible without login Plain text file LICENSE Data
Accessible without login Plain text file phpunit.xml.dist Data
Accessible without login Plain text file readme.md Doc. Documentation

  Files folder image Files  /  src  
File Role Description
Files folder imageWingu (1 directory)

  Files folder image Files  /  src  /  Wingu  
File Role Description
Files folder imageOctopusCore (1 directory)

  Files folder image Files  /  src  /  Wingu  /  OctopusCore  
File Role Description
Files folder imageEventDispatcher (12 files, 2 directories)

  Files folder image Files  /  src  /  Wingu  /  OctopusCore  /  EventDispatcher  
  Files folder image Files  /  src  /  Wingu  /  OctopusCore  /  EventDispatcher  /  EventNameMatcher  
File Role Description
  Plain text file AllNamesMatcher.php Class
  Plain text file EventNameMatcherFactory.php Class
  Plain text file EventNameMatcherInterface.php Class
  Plain text file NameMatcher.php Class
  Plain text file RegexMatcher.php Class
  Plain text file WildcardMatcher.php Class

  Files folder image Files  /  src  /  Wingu  /  OctopusCore  /  EventDispatcher  /  Exceptions  
File Role Description
  Plain text file Exception.php Class
  Plain text file InvalidArgumentException.php Class

  Files folder image Files  /  tests  
File Role Description
Files folder imageWingu (1 directory)

  Files folder image Files  /  tests  /  Wingu  
File Role Description
Files folder imageOctopusCore (1 directory)

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  
File Role Description
Files folder imageEventDispatcher (1 directory)

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  /  EventDispatcher  
File Role Description
Files folder imageTests (1 file, 2 directories)

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  /  EventDispatcher  /  Tests  
File Role Description
Files folder imageIntegration (2 files)
Files folder imageUnit (6 files, 1 directory)
  Accessible without login Plain text file TestCase.php Test

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  /  EventDispatcher  /  Tests  /  Integration  
File Role Description
  Accessible without login Plain text file EventDispatcherTest.php Test
  Accessible without login Plain text file TestCase.php Test

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  /  EventDispatcher  /  Tests  /  Unit  
File Role Description
Files folder imageEventNameMatcher (5 files)
  Accessible without login Plain text file EventDispatcherTest.php Test
  Accessible without login Plain text file EventDispatcherTraitTest.php Test
  Accessible without login Plain text file EventTest.php Test
  Accessible without login Plain text file ExceptionEventTest.php Test
  Accessible without login Plain text file SubscriptionTest.php Test
  Accessible without login Plain text file TestCase.php Test

  Files folder image Files  /  tests  /  Wingu  /  OctopusCore  /  EventDispatcher  /  Tests  /  Unit  /  EventNameMatcher  
File Role Description
  Accessible without login Plain text file AllNamesMatcherTest.php Test
  Accessible without login Plain text file EventNameMatcherFactoryTest.php Test
  Accessible without login Plain text file NameMatcherTest.php Test
  Accessible without login Plain text file RegexMatcherTest.php Test
  Accessible without login Plain text file WildcardMatcherTest.php Test

 Version Control Unique User Downloads Download Rankings  
 100%
Total:532
This week:0
All time:5,430
This week:621Up