phoole/event

Slim, powerful and full compatible PSR-14 event manager library for PHP

1.1.0 2019-11-19 06:57 UTC

This package is auto-updated.

Last update: 2023-01-19 14:14:03 UTC


README

Build Status Scrutinizer Code Quality Code Climate PHP 7 Latest Stable Version License

Slim, powerful and full compatible PSR-14 event manager library for PHP.

Installation

Install via the composer utility.

composer require "phoole/event"

or add the following lines to your composer.json

{
    "require": {
       "phoole/event": "1.*"
    }
}

Features

  • Full PSR-14 support

  • Support for classes want event-triggering capability with EventCapableTrait

  • Support for classes want event-listening capability with ListenerCapableTrait

Usage

  • Quick start

    use Phoole\Event\Provider;
    use Phoole\Event\Dispatcher;
    use Phoole\Event\Events\StoppableEvent;
    
    // create your own event class
    class MyEvent extends StoppableEvent {
    }
    
    // an invokable class for event handling
    class MyEventHandler
    {
        public function __invoke(MyEvent $event)
        {
             echo 'handling event...';
             return $event; // optional
        }
    } 
    
    // initiate event dispatcher
    $events = new Dispatcher(new Provider());
    
    // bind a callable with default priority 50 (0-100)
    $provider->attach(function(myEvent $event) {
        echo 'triggered...';
        return $event; // optional
    });
    
    // bind a invokable object with priority 80
    $provider->attach(new MyEventHandler(), 80);
    
    // fire the trigger, wil see output 'handling event...triggered...'
    $events->dispatch(new MyEvent());
  • Event hierarchy

    Instead of using event name to trigger like many event libraries were doing. PSR-14 compliant event libraries now only support triggering with event object. By setting up a meaningful event object hierarchy, developers may achieve great flexibility in event handling.

    Listeners will ONLY handle the events (and their subclasses) configured with the event parameter.

    use Phoole\Event\Events\StoppableEvent;
    
    // my own event hierarchy top
    class MyEvent extends StoppableEvent
    {
    }
    
    // my user authentication event
    class MyAuthEvent extends MyEvent
    {
        protected $userInfo;
    
        public function __construct(array $userInfo)
        {
            $this->userInfo = $userInfo;
        }
    
        public function getUserInfo(): array
        {
            return $this->userInfo;
        }
    }
    
    $provider = new Provider();
    $events = new Dispatcher($provider);
    
    // attach a listener to the event hierarchy top
    $provider->attach(function(MyEvent $event) {
        echo 'Event '.get_class($event).' fired';
        return $event; // optional
    });
    
    // attach a listener for logging users
    $provider->attach(function(MyAuthEvent $event)) use ($logger) {
        $logger->info(sprintf("User '%s' logged", $event->getUserInfo()['name']));
        return $event; // optional
    });
    
    ...
    
    // upon user logged in, trigger the event
    // BOTH listeners will process THIS event
    $events->dispatcher(new MyAuthEvent($userInfo));
  • Create a listener class

    A listener class may implement the ListenerCapableInterface and use ListenerCapableTrait.

    use Phoole\Event\ListenerCapableTrait;
    use Phoole\Event\ListenerCapableInterface;
    
    // my listener class
    class MyListener implements ListenerCapableInterface
    {
        use ListenerCapableTrait;
    
        // define on listener method
        public function MethodOne(MyEvent $event)
        {
             echo 'handling MyEvent in MethodOne...';
        }
        
        // define another listener method
        public function MethodTwo(MyEvent $event)
        {
            echo 'handling MyEvent in MethodTwo...';
        }
    
        // config this listener
        protected function eventsListening()
        {
            return [
                'MethodOne',
                ['MethodTwo', 80] // with priority 80
            ];
        }
    }
    
    // global dispatcher & provider
    $provider = new Provider();
    $events = new Dispatcher($provider);
    
    // set provider is enough
    $listener = new MyListener();
    $listener->setProvider($provider);
    
    // fire the event
    $events->dispatch(new MyEvent());

    Along with container library phoole/di, developer may not event worry about setting up dispatcher, provider or injecting the provider.

    use Phoole\Di\Container;
    
    // initiate the listener with dependencies injected
    $listener = Container::create(MyListener::class);
    
    // fire the event
    Container::events()->dispatch(new MyEvent());
  • Triggering events in your classes

    EventCapableInterface and EventCapableTrait give developers the ability of triggering events in their classes.

    use Phoole\Event\EventCapableTrait;
    use Phoole\Event\EventCapableInterface;
    
    class MyEventCapable implements EventCapableInterface
    {
        use EventCapableTrait;
    
        public function myMethod()
        {
             $this->triggerEvent(new MyEvent());
        }
    }
    
    // global dispatcher & provider
    $provider = new Provider();
    $events = new Dispatcher($provider);
    
    $eventCapable = new MyEventCapable();
    $eventCapable->setDispatcher($dispatcher);
    
    // will trigger an event
    $eventCapable->myMethod();

    Along with container library phoole/di, developer may not event worry about setting up dispatcher, provider or injecting the dispatcher.

    // initiate object with dependencies injected
    $eventCapable = Container::create(MyEventCapable::class);
    
    // will trigger an event
    $eventCapable->myMethod();

Testing

$ composer test

Dependencies

  • PHP >= 7.2.0

  • Phoole/base 1.*

License