PHP Classes
elePHPant
Icontem

PHP Event Dispatcher: Register events and call registered listeners

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Info   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 (1 year ago) RSS 2.0 feedNot yet rated by the usersTotal: 493 All time: 5,447 This week: 1,156Up
Version License PHP version Categories  
event-dispatcher 1.0.0MIT/X Consortium ...5.4PHP 5, Language, Design Patterns
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.

Picture of Protung Dragos
Name: Protung Dragos is available for providing paid consulting. Contact Protung Dragos .
Classes: 10 packages by
Country: Germany Germany
Age: 32
All time rank: 343 in Germany Germany
Week rank: 31 Up1 in Germany Germany Up
Innovation award
Innovation award
Nominee: 3x

Details provided by the author  
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:493All time:5,447
 This week:0This week:1,156Up