PHPackages joomla-x/event - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. joomla-x/event ActiveJoomla-package[Framework](/categories/framework) joomla-x/event ============== Joomla Event Package 1.2.0(10y ago)0240GPL-2.0+PHPPHP >=5.3.10|>=7.0 Since Jun 4Pushed 8y ago1 watchersCompare [ Source](https://github.com/joomla-x/event)[ Packagist](https://packagist.org/packages/joomla-x/event)[ Docs](https://github.com/joomla-framework/event)[ RSS](/packages/joomla-x-event/feed)WikiDiscussions master Synced 2w ago READMEChangelogDependencies (2)Versions (12)Used By (0) The Event Package [![Build Status](https://camo.githubusercontent.com/0e4238919e658e8602b0f48d1e5eacbff592eb725e02b0497c70fff7047c7d65/68747470733a2f2f7472617669732d63692e6f72672f6a6f6f6d6c612d782f6576656e742e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/joomla-x/event) =========================================================================================================================================================================================================================================================================================== [](#the-event-package-) The event package provides foundations to build event systems and an implementation supporting prioritized listeners. Events ------ [](#events) ### Example [](#example) An event has a name and can transport arguments. ``` namespace MyApp; use Joomla\Event\Event; // Creating an Event called "onSomething". $event = new Event('onSomething'); // Adding an argument named "foo" with value "bar". $event->addArgument('foo', 'bar'); // Setting the "foo" argument with a new value. $event->setArgument('foo', new \stdClass); // Getting the "foo" argument value. $foo = $event->getArgument('foo'); ``` Its propagation can be stopped ``` $event->stop(); ``` Event Listeners --------------- [](#event-listeners) An event listener can listen to one or more Events. You can create two types of listeners : using a class or a closure (anonymous function). **The functions MUST take an EventInterface (or children) as unique parameter.** ### Classes [](#classes) The listener listens to events having names matching its method names. ``` namespace MyApp; use Joomla\Event\EventInterface; /** * A listener listening to content manipulation events. */ class ContentListener { /** * Listens to the onBeforeContentSave event. */ public function onBeforeContentSave(EventInterface $event) { // Do something with the event, you might want to inspect its arguments. } /** * Listens to the onAfterContentSave event. */ public function onAfterContentSave(EventInterface $event) { } } ``` ### Closures [](#closures) Closures can listen to any Event, it must be declared when adding them to the Dispatcher (see below). ``` namespace MyApp; use Joomla\Event\EventInterface; $listener = function (EventInterface $event) { // Do something with the event, you might want to inspect its arguments. }; ``` The Dispatcher -------------- [](#the-dispatcher) The Dispatcher is the central point of the Event system, it manages the registration of Events, listeners and the triggering of Events. ### Registering Object Listeners [](#registering-object-listeners) Following the example above, you can register the `ContentListener` to the dispatcher : ``` namespace MyApp; use Joomla\Event\Dispatcher; // Creating a dispatcher. $dispatcher = new Dispatcher; /** * Adding the ContentListener to the Dispatcher. * By default, it will be registered to all events matching it's method names. * So, it will be registered to the onBeforeContentSave and onAfterContentSave events. */ $dispatcher->addListener(new ContentListener); ``` If the object contains other methods that should not be registered, you will need to explicitly list the events to be registered. For example: ``` $dispatcher->addListener( new ContentListener, array( 'onBeforeContentSave' => Priority::NORMAL, 'onAfterContentSave' => Priority::NORMAL, ) ); // Alternatively, include a helper method: $listener = new ContentListener; $dispatcher->addListener($listener, $listener->getEvents()); ``` ### Registering Closure Listeners [](#registering-closure-listeners) ``` namespace MyApp; use Joomla\Event\Dispatcher; use Joomla\Event\Priority; // Of course, it shouldn't be empty. $listener = function (EventInterface $event) { }; $dispatcher = new Dispatcher; /** * Adding a Closure Listener to the Dispatcher. * You must specify the event name and the priority of the listener. * Here, we register it for the onContentSave event with a normal Priority. */ $dispatcher->addListener( $listener, array('onContentSave' => Priority::NORMAL) ); ``` As you noticed, it is possible to specify a listener's priority for a given Event. It is also possible to do so with "object" Listeners. ### Filtering Listeners [](#filtering-listeners) DEPRECATED Listeners class can become quite complex, and may support public methods other than those required for event handling. The `setListenerFilter` method can be used to set a regular expression that is used to check the method names of objects being added as listeners. ``` // Ensure the dispatcher only registers "on*" methods. $dispatcher->setListenerFilter('^on'); ``` ### Registration with Priority [](#registration-with-priority) ``` namespace MyApp; use Joomla\Event\Dispatcher; use Joomla\Event\Priority; /** * Adding the ContentListener to the Dispatcher. * It will be registered with a high priority for the onBeforeContentSave, and * an "Above normal" priority for the onAfterContentSave event. */ $dispatcher->addListener( new ContentListener, array( 'onBeforeContentSave' => Priority::HIGH, 'onAfterContentSave' => Priority::ABOVE_NORMAL ) ); ``` The default priority is the `Priority::NORMAL`. When you add an "object" Listener without specifying the event names, it is registered with a NORMAL priority to all events. ``` /** * Here, it won't be registered to the onAfterContentSave event because * it is not specified. * * If you specify a priority for an Event, * then you must specify the priority for all Events. * * It is good pracctice to do so, it will avoid to register the listener * to "useless" events and by consequence save a bit of memory. */ $dispatcher->addListener( new ContentListener, array('onBeforeContentSave' => Priority::NORMAL) ); ``` If some listeners have the same priority for a given event, they will be called in the order they were added to the Dispatcher. ### Registering Events [](#registering-events) You can register Events to the Dispatcher, if you need custom ones. ``` namespace MyApp; use Joomla\Event\Dispatcher; use Joomla\Event\Event; // Creating an event with a "foo" argument. $event = new Event('onBeforeContentSave'); $event->setArgument('foo', 'bar'); // Registering the event to the Dispatcher. $dispatcher = new Dispatcher; $dispatcher->addEvent($event); ``` By default, an `Event` object is created with no arguments, when triggering the Event. Triggering Events ----------------- [](#triggering-events) Once you registered your listeners (and eventually events to the Dispatcher), you can trigger the events. The listeners will be called in a queue according to their priority for that Event. ``` // Triggering the onAfterSomething Event. $dispatcher->triggerEvent('onAfterSomething'); ``` If you registered an Event object having the `onAfterSomething` name, then it will be passed to all listeners instead of the default one. You can also pass a custom Event when triggering it ``` namespace MyApp; use Joomla\Event\Dispatcher; use Joomla\Event\Event; // Creating an event called "onAfterSomething" with a "foo" argument. $event = new Event('onAfterSomething'); $event->setArgument('foo', 'bar'); $dispatcher = new Dispatcher; // Triggering the onAfterSomething Event. $dispatcher->triggerEvent($event); ``` If you already added an Event with the onAfterSomething name using `addEvent`, then the event passed to the `triggerEvent` method will be chosen instead. Stopping the Propagation ------------------------ [](#stopping-the-propagation) As said above, you can stop the Event propagation if you are listening to an Event supporting it, it is the case for the `Event` class. ``` namespace MyApp; use Joomla\Event\Event; class ContentListener { public function onBeforeContentSave(Event $event) { // Stopping the Event propagation. $event->stop(); } } ``` When stopping the Event propagation, the next listeners in the queue won't be called. Observable classes ------------------ [](#observable-classes) Observable classes depend on a Dispatcher, and they may implement the `DispatcherAwareInterface` interface. Example of a Model class : ``` namespace MyApp; use Joomla\Event\DispatcherAwareInterface; use Joomla\Event\DispatcherInterface; use Joomla\Event\Event; class ContentModel implements DispatcherAwareInterface { const ON_BEFORE_SAVE_EVENT = 'onBeforeSaveEvent'; const ON_AFTER_SAVE_EVENT = 'onAfterSaveEvent'; /** * The underlying dispatcher. * * @var DispatcherInterface */ protected $dispatcher; public function save() { $this->dispatcher->triggerEvent(self::ON_BEFORE_SAVE_EVENT); // Perform the saving. $this->dispatcher->triggerEvent(self::ON_AFTER_SAVE_EVENT); } /** * Set the dispatcher to use. * * @param DispatcherInterface $dispatcher The dispatcher to use. * * @return DispatcherAwareInterface This method is chainable. */ public function setDispatcher(DispatcherInterface $dispatcher) { $this->dispatcher = $dispatcher; } } ``` Immutable Events ---------------- [](#immutable-events) An immutable event cannot be modified after its instantiation: - its arguments cannot be modified - its propagation can't be stopped It is useful when you don't want the listeners to manipulate it (they can only inspect it). ``` namespace MyApp; use Joomla\Event\EventImmutable; // Creating an immutable event called onSomething with an argument "foo" with value "bar" $event = new EventImmutable('onSomething', array('foo' => 'bar')); ``` The Delegating Dispatcher ------------------------- [](#the-delegating-dispatcher) A dispatcher that delegates its method to an other Dispatcher. It is an easy way to achieve immutability for a Dispatcher. ``` namespace MyApp; use Joomla\Event\DelegatingDispatcher; use Joomla\Event\Dispatcher; $dispatcher = new Dispatcher; // Here you add you listeners and your events.... // Instanciating a delegating dispatcher. $delegatingDispatcher = new DelegatingDispatcher($dispatcher); // Now you inject this dispatcher in your system, and it has only the triggerEvent method. ``` This is useful when you want to make sure that 3rd party applications, won't register or remove listeners from the Dispatcher. Installation via Composer ------------------------- [](#installation-via-composer) Add `"joomla-x/event": "3.0.*@dev"` to the require block in your composer.json and then run `composer install`. ``` { "require": { "joomla-x/event": "3.0.*@dev" } } ``` Alternatively, you can simply run the following from the command line: ``` composer require joomla-x/event "3.0.*@dev" ``` ### Health Score 30 — LowBetter than 62% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity11 Limited adoption so far Community13 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 63.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~144 days Recently: every ~218 days Total 8 Last Release 3760d ago PHP version history (2 changes)1.0-alphaPHP >=5.3.10 1.2.0PHP >=5.3.10|>=7.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/84f7f05685e84e3fe971d8d005bb74e766204799c50a7b45036af27436cecddc?d=identicon)[GreenCape](/maintainers/GreenCape) --- Top Contributors [![mbabker](https://avatars.githubusercontent.com/u/368545?v=4)](https://github.com/mbabker "mbabker (60 commits)")[![nibra](https://avatars.githubusercontent.com/u/827605?v=4)](https://github.com/nibra "nibra (13 commits)")[![wilsonge](https://avatars.githubusercontent.com/u/1986000?v=4)](https://github.com/wilsonge "wilsonge (8 commits)")[![dongilbert](https://avatars.githubusercontent.com/u/718028?v=4)](https://github.com/dongilbert "dongilbert (6 commits)")[![eddieajau](https://avatars.githubusercontent.com/u/700871?v=4)](https://github.com/eddieajau "eddieajau (4 commits)")[![florianv](https://avatars.githubusercontent.com/u/1586668?v=4)](https://github.com/florianv "florianv (3 commits)") --- Tags event-dispatcherevent-listenerjoomlajoomla-xphpeventframeworkjoomla ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/joomla-x-event/health.svg) ``` [![Health](https://phpackages.com/badges/joomla-x-event/health.svg)](https://phpackages.com/packages/joomla-x-event) ``` ### Alternatives [joomla/filter Joomla Filter Package 151.5M10](/packages/joomla-filter)[joomla/application Joomla Application Package 23430.4k13](/packages/joomla-application)[joomla/registry Joomla Registry Package 16505.8k21](/packages/joomla-registry)[joomla/filesystem Joomla Filesystem Package 11394.8k7](/packages/joomla-filesystem)[joomla/oauth2 Joomla OAuth2 Package 10326.4k2](/packages/joomla-oauth2) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)