---
title: "Phalcon Events"
version: "6.0"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Events
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Events\AbstractEventsAware
Abstract
This abstract class offers access to the events manager
- **`Phalcon\Events\AbstractEventsAware`**
- [`Phalcon\Acl\Adapter\AbstractAdapter`](/6.0/api/phalcon_acl/#acladapterabstractadapter)
- [`Phalcon\Queue\Consumer\QueueConsumer`](/6.0/api/phalcon_queue/#queueconsumerqueueconsumer)
### Method Summary
Returns the internal event manager
Sets the events manager
Helper method to fire an event
### Properties
### Methods
getEventsManager()
```php
public function getEventsManager(): ManagerInterface|null;
```
Returns the internal event manager
setEventsManager()
```php
public function setEventsManager( ManagerInterface $eventsManager ): void;
```
Sets the events manager
fireManagerEvent()
```php
protected function fireManagerEvent(
string $eventName,
mixed $data = null,
bool $cancellable = true,
bool $stopOnFalse = false
): mixed;
```
Helper method to fire an event
## Events\Event
Class
Phalcon\Events\Event
This class offers contextual information of a fired event in the
EventsManager
```php
Phalcon\Events\Event;
$event = new Event("db:afterQuery", $this, ["data" => "mydata"], true);
if ($event->isCancelable()) {
$event->stop();
}
```
- **`Phalcon\Events\Event`** - implements [`Phalcon\Events\EventInterface`](#eventseventinterface), [`Phalcon\Contracts\Events\Stoppable`](/6.0/api/phalcon_contracts/#contractseventsstoppable)
`Phalcon\Contracts\Events\Stoppable` · `Phalcon\Events\Exceptions\EventNotCancelable`
### Method Summary
Event constructor.
Check whether the event is cancelable.
Returns whether propagation must stop. PSR-14 alias backed by the same
Check whether the event is currently stopped.
Sets event data.
Sets event type.
Stops the event preventing propagation.
### Properties
Is event propagation stopped?
### Methods
__construct()
```php
public function __construct(
string $type,
object|null $source = null,
mixed $data = null,
bool $cancelable = true
);
```
Event constructor.
getData()
```php
public function getData(): mixed;
```
getSource()
```php
public function getSource(): object|null;
```
getType()
```php
public function getType(): string;
```
isCancelable()
```php
public function isCancelable(): bool;
```
Check whether the event is cancelable.
```php
if ($event->isCancelable()) {
$event->stop();
}
```
isPropagationStopped()
```php
public function isPropagationStopped(): bool;
```
Returns whether propagation must stop. PSR-14 alias backed by the same
`stopped` flag as `isStopped()`; calling `stop()` flips both.
isStopped()
```php
public function isStopped(): bool;
```
Check whether the event is currently stopped.
setData()
```php
public function setData( mixed $data = null ): EventInterface;
```
Sets event data.
setType()
```php
public function setType( string $type ): EventInterface;
```
Sets event type.
stop()
```php
public function stop(): EventInterface;
```
Stops the event preventing propagation.
```php
if ($event->isCancelable()) {
$event->stop();
}
```
## Events\EventInterface
Interface
Phalcon\Events\EventInterface
- [`Phalcon\Contracts\Events\Event`](/6.0/api/phalcon_contracts/#contractseventsevent)
- **`Phalcon\Events\EventInterface`**
`Phalcon\Contracts\Events\Event`
## Events\EventsAwareInterface
Interface
Phalcon\Events\EventsAwareInterface
- [`Phalcon\Contracts\Events\EventsAware`](/6.0/api/phalcon_contracts/#contractseventseventsaware)
- **`Phalcon\Events\EventsAwareInterface`**
`Phalcon\Contracts\Events\EventsAware`
## Events\Exception
Class
Phalcon\Events\Exception
Exceptions thrown in Phalcon\Events will use this class
- `\Exception`
- **`Phalcon\Events\Exception`**
- [`Phalcon\Events\Exceptions\EventNotCancelable`](#eventsexceptionseventnotcancelable)
- [`Phalcon\Events\Exceptions\InvalidEventHandler`](#eventsexceptionsinvalideventhandler)
- [`Phalcon\Events\Exceptions\InvalidEventSource`](#eventsexceptionsinvalideventsource)
- [`Phalcon\Events\Exceptions\InvalidEventType`](#eventsexceptionsinvalideventtype)
- [`Phalcon\Events\Exceptions\InvalidSubscriberConfiguration`](#eventsexceptionsinvalidsubscriberconfiguration)
- [`Phalcon\Events\Exceptions\NoListenersForEvent`](#eventsexceptionsnolistenersforevent)
## Events\Exceptions\EventNotCancelable
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\EventNotCancelable`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Events\Exceptions\InvalidEventHandler
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\InvalidEventHandler`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Events\Exceptions\InvalidEventSource
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\InvalidEventSource`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct(
string $type,
string $sourceType
);
```
## Events\Exceptions\InvalidEventType
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\InvalidEventType`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $eventType );
```
## Events\Exceptions\InvalidSubscriberConfiguration
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\InvalidSubscriberConfiguration`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $eventName );
```
## Events\Exceptions\NoListenersForEvent
Class
- `\Exception`
- [`Phalcon\Events\Exception`](#eventsexception)
- **`Phalcon\Events\Exceptions\NoListenersForEvent`**
`Phalcon\Events\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $eventType );
```
## Events\Manager
Class
Phalcon Events Manager, offers an easy way to intercept and manipulate, if
needed, the normal flow of operation. With the EventsManager the developer
can create hooks or plugins that will offer monitoring of data, manipulation,
conditional execution and much more.
- **`Phalcon\Events\Manager`** - implements [`Phalcon\Events\ManagerInterface`](#eventsmanagerinterface), `\Psr\EventDispatcher\EventDispatcherInterface`, [`Phalcon\Contracts\Events\Enumerable`](/6.0/api/phalcon_contracts/#contractseventsenumerable)
`Closure` · `Phalcon\Contracts\Events\Enumerable` · `Phalcon\Contracts\Events\Stoppable` · `Phalcon\Contracts\Events\Subscriber` · `Phalcon\Db\Event\AbstractModelEvent` · `Phalcon\Db\Event\ModelEventNameEnum` · `Phalcon\Events\Exceptions\InvalidEventHandler` · `Phalcon\Events\Exceptions\InvalidEventType` · `Phalcon\Events\Exceptions\InvalidSubscriberConfiguration` · `Phalcon\Events\Exceptions\NoListenersForEvent` · `Psr\EventDispatcher\EventDispatcherInterface` · `Psr\EventDispatcher\StoppableEventInterface` · `Throwable`
### Method Summary
Registers an event subscriber. The subscriber's getSubscribedEvents()
Returns if priorities are enabled
Attach a listener to the events manager
Removes every registered subscriber and detaches each listener they
Tells the event manager if it needs to collect all the responses returned
Detach the listener from the events manager
Removes all events from the EventsManager
Dispatches an object event to the appropriate event listeners.
Set if priorities are enabled in the EventsManager.
Fires an event in the events manager causing the active listeners to be
Fires an event and returns every listener's return value as an indexed
Internal handler to call a queue of events.
Returns every event type that currently has at least one listener,
Returns all the attached listeners of a certain type
Returns the configured method_exists-cache cap (0 = unlimited).
Returns all the responses returned by every handler executed by the last
Returns the list of registered subscriber instances.
Manager-level kill switch. After halt(), every fire()/fireAll()/
Check whether certain type of event has listeners
Check if the events manager is collecting all the responses returned by
Returns whether the manager-level kill switch is engaged. See halt().
Returns whether the stop-on-false short-circuit is enabled.
Returns whether strict mode is enabled.
Removes a previously registered subscriber. Detaches every listener the
Clears the manager-level kill switch set by halt().
Caps the number of distinct handler classes retained in the
Enables/disables the stop-on-false short-circuit. Default off.
Enables/disables strict mode. When true, fire()/fireAll() throw when
Extension seam invoked after an event has been dispatched to its
Extension seam invoked before an event is dispatched. The base
### Properties
Parsed-eventType cache. Memoizes the strpos + substr work done in
fire() so the same event name fired repeatedly collapses to a single
hash lookup.
Shape: `eventNameCache[$eventType] = [typePrefix, eventName]`
Listener storage. Shape:
events[$eventType] = [
[handler, type, priority] // types 0, 1, 3
[handler, type, priority, className] // type 2 carries
// resolved class name
...
]
`type` is classified once at attach() time so the dispatch loop can
route via a simple branch:
0 - Closure
1 - [obj, method] array callable
2 - plain object: method named after the event
3 - generic callable (string fn name, invokable object, etc.)
Re-entrancy depth of fire()/fireAll(). 0 means no fire is in progress.
Used to keep nested fire() calls from clobbering the outer caller's
`$this->responses` accumulator.
Manager-level kill switch. When true, every fire()/fireAll()/
fireQueue() call returns immediately without dispatching. Cleared by
resume().
Memoized method_exists() results for the plain-object dispatch path.
Keyed by `handlerClass => [methodName => bool]`.
Maximum number of distinct handler classes retained in
methodExistsCache. 0 (default) keeps the unbounded behavior.
When true, a listener returning literal `false` (with the event's
`cancelable` flag on) short-circuits the dispatch loop and pins the
fire() return as `false`. Default off.
When true, fire()/fireAll() throw on dispatch of an event that has zero
matching listeners. Default off.
Memoized getSubscribedEvents() maps keyed by Subscriber class name.
### Methods
addSubscriber()
```php
public function addSubscriber( Subscriber $subscriber ): void;
```
Registers an event subscriber. The subscriber's getSubscribedEvents()
map is parsed and each entry is attached through the regular listener
pipeline.
arePrioritiesEnabled()
```php
public function arePrioritiesEnabled(): bool;
```
Returns if priorities are enabled
attach()
```php
final public function attach(
array|string $eventType,
callable|object $handler,
int $priority = self::DEFAULT_PRIORITY
): void;
```
Attach a listener to the events manager
clearSubscribers()
```php
public function clearSubscribers(): void;
```
Removes every registered subscriber and detaches each listener they
contributed. Listeners attached via attach() are untouched.
collectResponses()
```php
public function collectResponses( bool $collect ): void;
```
Tells the event manager if it needs to collect all the responses returned
by every registered listener in a single fire
detach()
```php
public function detach(
string $eventType,
callable|object $handler
): void;
```
Detach the listener from the events manager
detachAll()
```php
public function detachAll( string|null $type = null ): void;
```
Removes all events from the EventsManager
dispatch()
```php
public function dispatch(
object $event,
array|string|null $name = null,
object|null $source = null
): mixed;
```
Dispatches an object event to the appropriate event listeners.
PSR-14 shaped: listeners receive the (possibly mutated) event object.
Propagation stops when the event implements
\{@see StoppableEventInterface\} and reports it is stopped.
enablePriorities()
```php
public function enablePriorities( bool $enablePriorities ): void;
```
Set if priorities are enabled in the EventsManager.
fire()
```php
public function fire(
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true,
bool|null $stopOnFalse = null
): mixed;
```
Fires an event in the events manager causing the active listeners to be
notified about it
```php
$eventsManager->fire("db", $connection);
```
fireAll()
```php
public function fireAll(
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true
): array;
```
Fires an event and returns every listener's return value as an indexed
array. Independent of collectResponses(); the caller's collected state
on `$this->responses` is preserved (stashed and restored).
fireQueue()
```php
final public function fireQueue(
array $queue,
EventInterface $event
): mixed;
```
Internal handler to call a queue of events.
Kept as a thin BC wrapper around the private dispatch loop.
getListenerMap()
```php
public function getListenerMap(): array;
```
Returns every event type that currently has at least one listener,
mapped to that type's listeners. Types contributed by subscribers are
included, because addSubscriber() attaches through the regular listener
pipeline.
Unwrapping is delegated to getListeners() so the internal shape of
$this->events is read in exactly one place.
getListeners()
```php
public function getListeners( string $type ): array;
```
Returns all the attached listeners of a certain type
getMethodExistsCacheLimit()
```php
public function getMethodExistsCacheLimit(): int;
```
Returns the configured method_exists-cache cap (0 = unlimited).
getResponses()
```php
public function getResponses(): array;
```
Returns all the responses returned by every handler executed by the last
'fire' executed
getSubscribers()
```php
public function getSubscribers(): array;
```
Returns the list of registered subscriber instances.
halt()
```php
public function halt(): void;
```
Manager-level kill switch. After halt(), every fire()/fireAll()/
fireQueue() call returns immediately without dispatching, until
resume() is called.
hasListeners()
```php
public function hasListeners( string $type ): bool;
```
Check whether certain type of event has listeners
isCollecting()
```php
public function isCollecting(): bool;
```
Check if the events manager is collecting all the responses returned by
every registered listener in a single fire
isHalted()
```php
public function isHalted(): bool;
```
Returns whether the manager-level kill switch is engaged. See halt().
isStopOnFalse()
```php
public function isStopOnFalse(): bool;
```
Returns whether the stop-on-false short-circuit is enabled.
isStrict()
```php
public function isStrict(): bool;
```
Returns whether strict mode is enabled.
isValidHandler()
```php
public function isValidHandler( mixed $handler ): bool;
```
removeSubscriber()
```php
public function removeSubscriber( Subscriber $subscriber ): void;
```
Removes a previously registered subscriber. Detaches every listener the
subscriber declared via getSubscribedEvents(). Idempotent.
resume()
```php
public function resume(): void;
```
Clears the manager-level kill switch set by halt().
setMethodExistsCacheLimit()
```php
public function setMethodExistsCacheLimit( int $methodExistsCacheLimit ): void;
```
Caps the number of distinct handler classes retained in the
method_exists memoization cache. 0 disables the cap.
setStopOnFalse()
```php
public function setStopOnFalse( bool $flag ): void;
```
Enables/disables the stop-on-false short-circuit. Default off.
setStrict()
```php
public function setStrict( bool $strict ): void;
```
Enables/disables strict mode. When true, fire()/fireAll() throw when
dispatching an event with zero matching listeners.
afterFire()
```php
protected function afterFire(
mixed $status,
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true
): mixed;
```
Extension seam invoked after an event has been dispatched to its
listener queues. The base implementation returns `status` unchanged.
beforeFire()
```php
protected function beforeFire(
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true
): bool;
```
Extension seam invoked before an event is dispatched. The base
implementation returns true, so dispatch proceeds. Returning false
aborts the dispatch entirely.
## Events\ManagerInterface
Interface
Phalcon\Events\ManagerInterface
- [`Phalcon\Contracts\Events\Manager`](/6.0/api/phalcon_contracts/#contractseventsmanager)
- **`Phalcon\Events\ManagerInterface`**
`Phalcon\Contracts\Events\Manager`
## Events\PsrEventInterface
Interface
- **`Phalcon\Events\PsrEventInterface`**
## Events\Traits\EventsAwareTrait
Trait
- **`Phalcon\Events\Traits\EventsAwareTrait`**
`Phalcon\Events\Exception` · `Phalcon\Events\Manager` · `Phalcon\Events\ManagerInterface` · `Phalcon\Events\PsrEventInterface`
[`Phalcon\Application\AbstractApplication`](/6.0/api/phalcon_application/#applicationabstractapplication) · [`Phalcon\Auth\Guard\AbstractGuard`](/6.0/api/phalcon_auth/#authguardabstractguard) · [`Phalcon\Autoload\Loader`](/6.0/api/phalcon_autoload/#autoloadloader) · [`Phalcon\Cache\AbstractCache`](/6.0/api/phalcon_cache/#cacheabstractcache) · [`Phalcon\Cli\Task`](/6.0/api/phalcon_cli/#clitask) · [`Phalcon\DataMapper\Pdo\ConnectionLocator`](/6.0/api/phalcon_datamapper/#datamapperpdoconnectionlocator) · [`Phalcon\DataMapper\Pdo\Connection\AbstractConnection`](/6.0/api/phalcon_datamapper/#datamapperpdoconnectionabstractconnection) · [`Phalcon\Db\Adapter\AbstractAdapter`](/6.0/api/phalcon_db/#dbadapterabstractadapter) · [`Phalcon\Di\Di`](/6.0/api/phalcon_di/#didi) · [`Phalcon\Dispatcher\AbstractDispatcher`](/6.0/api/phalcon_dispatcher/#dispatcherabstractdispatcher) · [`Phalcon\Http\Request`](/6.0/api/phalcon_http/#httprequest) · [`Phalcon\Http\Response`](/6.0/api/phalcon_http/#httpresponse) · [`Phalcon\Mvc\Controller`](/6.0/api/phalcon_mvc/#mvccontroller) · [`Phalcon\Mvc\Dispatcher`](/6.0/api/phalcon_mvc/#mvcdispatcher) · [`Phalcon\Mvc\Micro`](/6.0/api/phalcon_mvc/#mvcmicro) · [`Phalcon\Mvc\Model\Manager`](/6.0/api/phalcon_mvc/#mvcmodelmanager) · [`Phalcon\Mvc\Router`](/6.0/api/phalcon_mvc/#mvcrouter) · [`Phalcon\Mvc\View`](/6.0/api/phalcon_mvc/#mvcview) · [`Phalcon\Mvc\View\Engine\AbstractEngine`](/6.0/api/phalcon_mvc/#mvcviewengineabstractengine) · [`Phalcon\Mvc\View\Simple`](/6.0/api/phalcon_mvc/#mvcviewsimple) · [`Phalcon\Storage\Adapter\AbstractAdapter`](/6.0/api/phalcon_storage/#storageadapterabstractadapter)
### Method Summary
Returns the internal event manager
Sets the events manager
Helper method to fire an event
### Properties
### Methods
getEventsManager()
```php
public function getEventsManager(): ManagerInterface|null;
```
Returns the internal event manager
setEventsManager()
```php
public function setEventsManager( ManagerInterface $eventsManager ): void;
```
Sets the events manager
fireManagerEvent()
```php
protected function fireManagerEvent(
string $eventName,
mixed $data = null,
bool $cancellable = true,
bool $stopOnFalse = false
);
```
Helper method to fire an event
firePsrEvent()
```php
protected function firePsrEvent(
PsrEventInterface $event,
string|null $name = null
): mixed;
```
Source: https://docs.phalcon.io/6.0/api/phalcon_events/index.mdx