phossa/phossa-event

A event management library for PHP

1.0.7 2016-05-27 03:38 UTC

This package is not auto-updated.

Last update: 2024-03-16 16:10:29 UTC


README

Build Status Latest Stable Version License

See new lib at phoole/event Introduction

Phossa-event is an event management library for PHP. It decoupled from any packages other than the phossa/phossa-shared. It requires PHP5.4 only.

Installation

Install via the composer utility.

composer require "phossa/phossa-event=1.*"

or add the following lines to your composer.json

{
    "require": {
       "phossa/phossa-event": "1.*"
    }
}

Simple EventDispatcher

Simple event dispatching using Phossa\Event\EventDispatcher

  • Simple usage

    $dispatcher = new EventDispatcher();
    
    // bind event 'user.login' to a callable
    $dispatcher->on('user.login', function(Event $evt) {
        // ...
    });
    
    // trigger the 'user.login' event, passing data
    $dispatcher->trigger('user.login', [ 'user' => $user ]);

    or use statically (global dispatching)

    // bind event with priority 60 (0 - 100, high # higher priority)
    EventDispatcher::on('user.login', function(Event $evt) {
        // ...
    }, 60);
    
    // trigger the 'user.login' event
    EventDispatcher::trigger('user.login', [ 'user' => $user ]);
  • Trigger for limited times

    // bind event for once
    $dispatcher->one('user.login', function(Event $evt) {
        // ...
    });
    
    // allow 3 times
    $dispatcher->many('user.tag', 3, function(Event $evt) {
        // ...
    });
  • Event globbing

    // globbing
    $dispatcher->on('user.*', function(Event $evt) {
        //...
    });
  • Detach events

    // detach
    $dispatcher->off('user.*');
  • Monitoring PHP errors

    Execute a callable when PHP error happens.

    // callable returns bool
    $dispatcher->error(function($errno$errstr$errfile$errline) {
        // ...
        return true;
    });
  • Execute a callable when script finishes

    // run this after script ends
    $dispatcher->ready(function() {
        // ...
    });

Full-fledged EventManager

Complex event management using Phossa\Event\EventManager with full fledge support for event listener, event subject, local event manager and global event manageretc.

  • Event listener

    use Phossa\Event\Interfaces;
    
    class MyListener implements Interfaces\EventListenerInteface
    {
        /*
         * Get events and callables MyListener listens to
         */
        public function getEventsListening()
        {
            return array(
                'eventName1' => 'method1', // method1 of $this
                'eventName2' => array('method2', 20), // priority 20
                'eventName3' => array( // multiple callables
                    [ 'method3', 70 ],
                    [ 'method4', 50 ]
                )
            );
        }
    }
    
    $listener = new MyListener();
  • Event manager

    // create an event manager
    $evtManager = new Event\EventManager();
    
    // attach a listener object
    $evtManager->attachListener($listener);
    
    // attach a callable directly to 'oneSpecialEvent'
    $callable = function(Event\Event $evt) {
        ...
    };
    $evtManager->attachListener($callable, 'oneSpecialEvent');
    
    // detach a callable
    $evtManager->detachListener($callable);
  • The event-aware subject

    use Phossa\Event\Interfaces;
    
    class MyEventAware implements Interfaces\EventAwareInterface
    {
        // add setEventManager() and triggerEvent()
        use Interfaces\EventAwareTrait;
    
        ...
    }
    
    $subject = new MyEventAware();
  • Combine together

    // set manager to event-aware subject
    $subject->setEventManager($evtManager);
    
    // trigger event
    $subject->triggerEvent('eventName2');
  • Event globbing

    Able to listen to all events by using '' or 'event'.

    use Phossa\Event\Interfaces\EventListenerInterface;
    
    class Listener implements EventListenerInterface
    {
        public function getEventsListening()
        {
            return [
                'evtTest1' => 'testC',
                'evtTest2' => [ 'testD', 20 ],
                'evtTest3' => [
                    [ 'testA', 70 ],
                    [ 'testB', 50 ]
                ],
                // globbing
                'evt*' => 'bingo',
                'evtTest*' => 'bingo2',
                '*' => 'wow',
            ];
        }
    }
  • Event management for static classes.

    The static listener class,

    use Phossa\Event\Interfaces;
    
    class StaticListener implements Interfaces\EventListenerStaticInteface
    {
        /*
         * Get events and callables StaticListener listens to
         */
        public static function getEventsListening()
        {
            return array(
                'eventName1' => 'method1', // method1 of $this
                'eventName2' => array('method2', 20), // priority 20
                'eventName3' => array( // multiple callables
                    [ 'method3', 70 ],
                    [ 'method4', 50 ]
                )
            );
        }
    }

    The static subject class to use events,

    use Phossa\Event\Interfaces;
    
    class StaticEventAware implements Interfaces\EventAwareStaticInterface
    {
        // add setEventManager() and triggerEvent()
        use Interfaces\EventAwareStaticTrait;
    
        ...
    }

    The static subject class trigger events as follows,

    // create an event manager/dispatcher
    $evtManager = new Event\EventManager();
    
    // attach a static listener class
    $evtManager->attachListener(StaticListener::CLASS);
    
    // set manager/dispatcher to event-aware static subject class
    StaticEventAware::setEventManagerStatically($evtManager);
    
    // trigger event by the static subject class
    StaticEventAware::triggerEventStatically('eventName2');
  • Composite event manager

    Able to use composite event manager as follows,

    use Phossa\Event;
    
    // global event manager
    $global_manager = new Event\EventManager();
    $global_manager->attachListener($some_global_event_listener);
    
    // local event manager
    $local_manager  = new Event\Variation\EventManagerComposite();
    $local_manager->attachListener($local_listener);
    
    // allow local event manager dispatch events to global event manager
    $local_manager->setOtherManager('global', $global_manager);
    
    // the event aware subject
    $subject = new MyEventAware();
    
    // set event manager
    $subject->setEventManager($local_manager);
    
    // fire up an event, will look into event handling queue from both
    // $local_manager and $global_manager
    $subject->triggerEvent('some_event');
  • Immutable event manager

    use Phossa\Event;
    
    // low-level manager to hide
    $_evtManager = new EventManager();
    $_evtManager->attachListener(...);
    ...
    
    // expose an immutable event managet to user
    $evtManager = new Variation\ImmutableEventManager($_evtManager);
    
    // cause an exception
    $evtManager->detachListener( ... );
  • Shareable event manager, a single copy of global manager and lots of local managers.

    // get global copy by using static method `getInstance()`
    $globalEventManager = ShareableEventManager::getInstance();
    
    // normal event managers
    $localEventManager  = new ShareableEventManager();
    
    // is this the global copy?
    if ($evtManager->isShareable()) {
        ...
    } else {
        ...
    }

Features

  • Supports PHP 5.4+, PHP 7.0+, HHVM.

  • PHP7 ready for return type declarations and argument type declarations.

  • PSR-1, PSR-2, PSR-4 compliant.

  • Decoupled packages can be used seperately without the framework.

Dependencies

  • PHP >= 5.4.0

  • phossa/phossa-shared >= 1.0.8

License

MIT License