phossa2/event

PSR-14 event manager implementation libraray for PHP

2.1.6 2016-08-26 01:39 UTC

README

PLEASE USE phoole/event library instead

Build Status Code Quality Code Climate PHP 7 ready HHVM Latest Stable Version License

phossa2/event is a PSR-14 event manager library for PHP.

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-4 and the upcoming PSR-14

Installation

Install via the composer utility.

composer require "phossa2/event=2.1.*"

or add the following lines to your composer.json

{
    "require": {
       "phossa2/event": "^2.1.0"
    }
}

Features

Usage

  • Quick start

    use Phossa2\Event\EventDispatcher;
    
    // event dispatcher
    $events = new EventDispatcher();
    
    // bind event with a callback
    $events->attach('login.success', function($evt) {
        echo "logged in as ". $evt->getParam('username');
    });
    
    // bind event with a callable
    $events->attach('login.attempt', [$logger, 'logEvent']);
    
    // unbind an event
    $events->clearListeners('login.attempt');
    
    // fire the trigger
    $events->trigger('login.success');
  • Event name globbing

    Event name globbing means callables of the binding 'login.*' will also be triggered when triggering event 'login.success'.

    // bind 'login.*' with callables
    $events->attach('login.*', function($evt) {
        echo $evt->getName();
    });
    
    // trigger 'login.atttempt' will also trigger callables of 'login.*'
    $events->trigger('login.attempt');

    The globbing rules are similiar to the PHP function glob(), where

    • * in the string means any chars except the dot.

    • If * at the end, will match any chars including the dot. e.g. login.* will match 'login.attempt.before'.

    • . means the dot.

    • one-char-string * means match any string (including the dot).

    Note: Name globbing ONLY happens when event is being triggered. Binding or unbinding events only affect the EXACT event name.

    // unbind the exact 'login.*'
    $events->clearListeners('login.*');
  • Shared event manager support

    Class EventDispatcher implements the Phossa2\Shared\Shareable\ShareableInterface.

    ShareableInterface is an extended version of singleton pattern. Instead of supporting only one shared instance, Classes implements ShareableInterface may have shared instance for different scope.

    // global event manager, global scope is ''
    $globalEvents = EventDispatcher::getShareable();
    
    // shared event manager in scope 'MVC'
    $mvcEvents = EventDispatcher::getShareable('MVC');
    
    // an event manager instance, which has scope 'MVC'
    $events = new EventDispatcher('MVC');
    
    // in scope MVC ?
    var_dump($events->hasScope('MVC')); // true
    
    // in global scope ?
    var_dump($events->hasScope()); // true

    Callables bound to a shared manager will also be triggered if an event manager instance has the same scope.

    // shared event manager in scope 'MVC'
    $mvcEvents = EventDispatcher::getShareable('MVC');
    
    // bind with pirority 100 (highest priority)
    $mvcEvents->attach('*', function($evt) {
        echo "mvc";
    }, 100);
    
    // create a new instance within the MVC scope
    $events = new EventDispatcher('MVC');
    
    // bind with default priority 0
    $events->attach('test', function($evt) {
        echo "test";
    });
    
    // will also trigger matched events in $mvcEvents
    $events->trigger("test");

    Event manager instance can have multiple scopes, either specified during the instantiation or using addScope().

    // create an event manager with 2 scopes
    $events = new EventDispatcher(['MVC', 'AnotherScope']);
    
    // add another scope
    $events->addScope('thirdScope');

    Couple of helper methods are provided for on/off/trigger events with shared managers.

    // bind a callable to global event manager
    EventDispatcher::onGlobalEvent('login.success', function() {});
    
    // use interface name as a scope
    EventDispatcher::onEvent(
        'Psr\\Log\\LoggerInterface', // scope
        'log.error', // event name
        function () {}
    );
    
    // unbind all callables of event 'log.error' in a scope
    EventDispatcher::offEvent(
        'Psr\\Log\\LoggerInterface',
        'log.error'
    );
    
    // unbind *ALL* events in global scope
    EventDispatcher::offGlobalEvent();
  • Attaching a listener

    Listener implements the ListenerInterface. Or in short, provides a method eventsListening().

    use Phossa2\Event\Interfaces\ListenerInterface;
    
    class myListener implements ListenerInterface
    {
        public function eventsListening()
        {
            return [
                // one method of $this
                eventName1 => 'method1',
    
                // 2 methods
                eventName2 => ['callable1', 'method2'],
    
                // priority 20 and in a 'mvcScope' scope
                eventName2 => ['method2', 20, 'mvcScope'], // with priority 20
    
                eventName3 => [
                    ['method3', 50],
                    ['method4', 70, 'anotherScope']
                ]
            ];
        }
    }

    EventDispatcher::attachListener() can be used to bind events defined in eventsListening() instead of using EventDispatcher::attach() to bind each event manually.

    $events = new EventDispatcher();
    
    $listener = new \myListener();
    
    // bind all events defined in $listener->eventsListening()
    $events->attachListener($listener);
    
    // will call $listener->method1()
    $events->trigger('eventName1');
  • Using event manager statically

    StaticEventDispatcher is a static wrapper for an EventDispatcher slave.

    StaticEventDispatcher::attach('*', function($evt) {
        echo 'event ' . $evt->getName();
    });
    
    // will print 'event test'
    StaticEventDispatcher::trigger('test');

    StaticEventDispatcher is not the same as global event manager. StaticEventDispatcher has a default slave which is a shared event manager in scope '__STATIC__'. While global event manager is the shared event manager in global scope ''.

    User may set another event manager to replace the default slave.

    StaticEventDispatcher::setEventManager(new EventDispatcher());
  • EventCapableAbstract

    EventCapableAbstract implements both ListenerInterface and EventCapableInterface. It will do the following when triggerEvent() is called,

    • Get the event manager. If it is not set yet, create one default event manager with current classname as scope.

    • Attach events defined in eventsListening() if not yet.

    • Trigger the event and processed by the event manager and all of the shared managers of its scopes.

    class LoginController extends EventCapableAbstract
    {
        public function login() {
    
            // failed
            if (!$this->trigger('login.pre')) {
                return;
            }
    
            // ...
        }
    
        public function beforeLogin() {
            // ...
        }
    
        public function eventsListening()
        {
            return [
                'login.pre' => 'beforeLogin'
            ];
        }
    }
  • EventableExtensionAbstract and EventableExtensionCapableAbstract

    EventableExtensionCapableAbstract is the base class supporting events and extensions.

    Detail usage can be found in phossa2/cache Phossa2\Cache\CachePool extends EventableExtensionCapableAbstract and Phossa2\Cache\Extension\ByPass extends EventableExtensionAbstract.

    Or look at phossa2/route.

  • Class or interface level events support

    Class or interface name can be used as the scope. When events bound to these kind of scopes, any events triggered by child class will also search callables defined in parent class/interface level shared event managers.

    // define event '*' for interface 'MyInterface'
    EventDispatcher::onEvent(
        'MyInterface', '*', function() { echo "MyInterface"; }, 60
    );

    Extends EventCapableAbstract.

    class MyClass extends EventCapableAbstract implements MyInterface
    {
        public function myMethod()
        {
            echo "myMethod";
        }
    
        public function eventsListening()/*# : array */
        {
            return [
                // priority 20
                'afterTest' => ['myMethod', 20]
            ];
        }
    }
    
    $obj = new MyClass();
    
    // will trigger callable 'myMethod' and handlers for 'MyInterface'
    $obj->trigger('afterTest');
  • Execute callable for limited times

    // bind a callable for executing only once
    $events->one('user.login', function(Event $evt) {
        // ...
    });
    
    // 3 times
    $events->many(3, 'user.tag', function(Event $evt) {
        // ...
    });

Change log

Please see CHANGELOG from more information.

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information.

Dependencies

  • PHP >= 5.4.0

  • phossa2/shared >= 2.0.21

License

MIT License