event

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

• Apache 2.0