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

  usePhoole\Event\Provider;
  usePhoole\Event\Dispatcher;
  usePhoole\Event\Events\StoppableEvent;
  // create your own event classclass MyEvent extends StoppableEvent {
  }
  // an invokable class for event handlingclass MyEventHandler
  {
  publicfunction__invoke(MyEvent$event)
  {
  echo'handling event...';
  return$event; // optional
  }
  } // initiate event dispatcher$events = newDispatcher(newProvider());
  // 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(newMyEventHandler(), 80);
  // fire the trigger, wil see output 'handling event...triggered...'$events->dispatch(newMyEvent());

• 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.

  usePhoole\Event\Events\StoppableEvent;
  // my own event hierarchy topclass MyEvent extends StoppableEvent
  {
  }
  // my user authentication eventclass MyAuthEvent extends MyEvent
  {
  protected$userInfo;
  publicfunction__construct(array$userInfo)
  {
  $this->userInfo = $userInfo;
  }
  publicfunctiongetUserInfo(): array
  {
  return$this->userInfo;
  }
  }
  $provider = newProvider();
  $events = newDispatcher($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(newMyAuthEvent($userInfo));

• Create a listener class

  A listener class may implement the ListenerCapableInterface and use ListenerCapableTrait.

  usePhoole\Event\ListenerCapableTrait;
  usePhoole\Event\ListenerCapableInterface;
  // my listener classclass MyListener implements ListenerCapableInterface
  {
  use ListenerCapableTrait;
  // define on listener methodpublicfunctionMethodOne(MyEvent$event)
  {
  echo'handling MyEvent in MethodOne...';
  }
  // define another listener methodpublicfunctionMethodTwo(MyEvent$event)
  {
  echo'handling MyEvent in MethodTwo...';
  }
  // config this listenerprotectedfunctioneventsListening()
  {
  return [
  'MethodOne',
  ['MethodTwo', 80] // with priority 80
  ];
  }
  }
  // global dispatcher & provider$provider = newProvider();
  $events = newDispatcher($provider);
  // set provider is enough$listener = newMyListener();
  $listener->setProvider($provider);
  // fire the event$events->dispatch(newMyEvent());

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

  usePhoole\Di\Container;
  // initiate the listener with dependencies injected$listener = Container::create(MyListener::class);
  // fire the event
  Container::events()->dispatch(newMyEvent());

• Triggering events in your classes

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

  usePhoole\Event\EventCapableTrait;
  usePhoole\Event\EventCapableInterface;
  class MyEventCapable implements EventCapableInterface
  {
  use EventCapableTrait;
  publicfunctionmyMethod()
  {
  $this->triggerEvent(newMyEvent());
  }
  }
  // global dispatcher & provider$provider = newProvider();
  $events = newDispatcher($provider);
  $eventCapable = newMyEventCapable();
  $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