---
title: "Phalcon Events"
version: "5.20"
---
> 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`](/5.20/api/phalcon_acl/#acladapterabstractadapter)
- [`Phalcon\Queue\Consumer\QueueConsumer`](/5.20/api/phalcon_queue/#queueconsumerqueueconsumer)
`Phalcon\Events\ManagerInterface`
### 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|bool;
```
Helper method to fire an event
## Events\Event
Class
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`](/5.20/api/phalcon_contracts/#contractseventsstoppable)
`Phalcon\Contracts\Events\Stoppable` · `Phalcon\Events\Exceptions\EventNotCancelable` · `Phalcon\Events\Exceptions\InvalidEventSource`
### Method Summary
Phalcon\Events\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 cancelable?
Event data
Event source
Is event propagation stopped?
Event type
### Methods
__construct()
```php
public function __construct(
string $type,
mixed $source = null,
mixed $data = null,
bool $cancelable = true
);
```
Phalcon\Events\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`](/5.20/api/phalcon_contracts/#contractseventsevent)
- **`Phalcon\Events\EventInterface`**
`Phalcon\Contracts\Events\Event`
## Events\EventsAwareInterface
Interface
Phalcon\Events\EventsAwareInterface
- [`Phalcon\Contracts\Events\EventsAware`](/5.20/api/phalcon_contracts/#contractseventseventsaware)
- **`Phalcon\Events\EventsAwareInterface`**
`Phalcon\Contracts\Events\EventsAware`
## Events\Exception
Class
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), [`Phalcon\Contracts\Events\Enumerable`](/5.20/api/phalcon_contracts/#contractseventsenumerable)
`Closure` · `Phalcon\Contracts\Events\Enumerable` · `Phalcon\Contracts\Events\Stoppable` · `Phalcon\Contracts\Events\Subscriber` · `Phalcon\Events\Exceptions\InvalidEventHandler` · `Phalcon\Events\Exceptions\InvalidEventType` · `Phalcon\Events\Exceptions\InvalidSubscriberConfiguration` · `Phalcon\Events\Exceptions\NoListenersForEvent`
### 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 its listeners, routed by an explicit name
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
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. Useful for
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 all the responses returned
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. When true, fire()/fireAll()
Removes a previously registered subscriber. Detaches every listener the
Clears the manager-level kill switch set by halt(). Subsequent
Caps the number of distinct handler classes retained in the
Enables/disables the stop-on-false short-circuit. When true, a
Enables/disables strict mode. When true, fire()/fireAll() throw
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 (the common case
for db:beforeQuery, model:afterSave, etc.) collapses to a single
hash lookup.
Shape: `eventNameCache[$eventType] = [typePrefix, eventName]`
Unbounded by design - distinct event types in a typical Phalcon
application are well under 100 keys, and the cache never needs
invalidation (parse is deterministic for a given eventType string).
Listener storage. Shape:
events[$eventType] = [
[handler, type, priority] // types 0, 1, 3
[handler, type, priority, className] // type 2 carries
// resolved class name
...
]
Kept sorted by priority descending when priorities are enabled
(FIFO within the same priority); otherwise listeners are simply
appended in attach order.
`type` is classified once at attach() time so dispatch() can
route via a simple branch:
0 - Closure: direct invocation via `{handler}(args)`, no
arg-array alloc per call
1 - [obj, method] array callable: direct dynamic dispatch
`handler[0]->{handler[1]}(args)`
2 - plain object: dynamic dispatch via method named after the
event (the classic Phalcon listener pattern); class name is
captured at attach time to skip get_class() per fire
3 - generic callable (string fn name, invokable object,
[class, staticMethod]): call_user_func_array
Re-entrancy depth of fire()/fireAll(). 0 means no fire is in
progress. Incremented on every fire entry, decremented on exit.
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 (null or empty array) without
dispatching. Cleared by resume(). Survives across fire() calls,
unlike Event::stop() which only stops the current dispatch chain.
Memoized method_exists() results for the OBJECT_METHOD dispatch
path in dispatch(). Keyed by `handlerClass => [methodName => bool]`.
A class doesn't gain methods at runtime so the lookup is permanent.
Maximum number of distinct handler classes retained in
methodExistsCache. 0 (default) keeps the original unbounded
behavior; a positive value clears the cache when adding a new
class would exceed it. Re-warming is cheap (method_exists is
O(1)) and the cap is meant for very long-lived workers that see
many distinct listener classes over time.
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 - preserves the pre-5.13
"last-wins" contract for codebases that rely on later listeners
overriding an earlier false return [#17019].
When true, fire()/fireAll() throw on dispatch of an event that
has zero matching listeners. Catches typos in dev. Default off.
Memoized getSubscribedEvents() maps keyed by Subscriber class name.
The static method's return is stable for the lifetime of a class
definition, so the cache never needs invalidation.
### 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(
string $eventType,
mixed $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.
Iterates a snapshot of `subscribers` so removeSubscriber() can safely
mutate the original property during the walk.
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,
mixed $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,
mixed $name = null,
mixed $source = null
);
```
Dispatches an object event to its listeners, routed by an explicit name
(a string, or a [class, method] array) or, failing that, by the event's
class name. Listeners receive the event object. Propagation stops when
the event implements Phalcon\Contracts\Events\Stoppable and reports it
is stopped.
enablePriorities()
```php
public function enablePriorities( bool $enablePriorities ): void;
```
Set if priorities are enabled in the EventsManager.
A priority queue of events is a data structure similar
to a regular queue of events: we can also put and extract
elements from it. The difference is that each element in a
priority queue is associated with a value called priority.
This value is used to order elements of a queue: elements
with higher priority are retrieved before the elements with
lower priority.
fire()
```php
public function fire(
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true,
mixed $stopOnFalse = null
);
```
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 across the call).
```php
$results = $eventsManager->fireAll("db:beforeQuery", $connection);
```
fireQueue()
```php
final public function fireQueue(
array $queue,
EventInterface $event
);
```
Internal handler to call a queue of events.
Kept at its original 2-arg signature for BC; thin wrapper around
the private `dispatch()` helper. Direct callers pay the cost of
re-extracting metadata from the Event; the framework's own fire()
path bypasses this wrapper and calls dispatch() with hoisted args.
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).
See setMethodExistsCacheLimit().
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. Useful for
introspection and test setup/teardown.
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. Use this when a listener needs to abort all
subsequent event activity for the lifetime of the manager (e.g.
a security check that cancels everything downstream).
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 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.
See setStopOnFalse().
isStrict()
```php
public function isStrict(): bool;
```
Returns whether strict mode is enabled. When true, fire()/fireAll()
throw when an event has no matching listeners - useful in dev to
catch typos. Default off.
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 - calling
with a subscriber that was never added (or already removed) is a no-op.
resume()
```php
public function resume(): void;
```
Clears the manager-level kill switch set by halt(). Subsequent
fire()/fireAll()/fireQueue() calls resume normal dispatch.
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 (the
default; preserves the original unbounded behavior). When the
cap is exceeded, the cache is cleared and re-warms on subsequent
fires.
setStopOnFalse()
```php
public function setStopOnFalse( bool $flag ): void;
```
Enables/disables the stop-on-false short-circuit. When true, a
listener returning literal `false` (with cancelable=true) stops
the current event's queue and pins the fire() return as `false`.
Later listeners cannot overwrite the cancel. Default off.
Independent of halt() / event->stop() - only governs how the
dispatch loop reacts to a `false` listener return.
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. Receives the computed dispatch result as `status`
and returns the value fire() hands back to its caller; the base
implementation returns `status` unchanged. A subclass can override
it to run bookkeeping or to post-process / rewrite the result.
Only called when the event was actually dispatched; the halted and
no-listener short-circuits in fire() return before reaching it.
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 unchanged. A
subclass can override it to inspect the source and data and, by
returning false, abort the dispatch entirely - for example to
redirect a deferred event onto an external queue. Invoked before the
no-listener short-circuits, so it sees every fire(), including those
with no locally attached listeners.
## Events\ManagerInterface
Interface
Phalcon\Events\ManagerInterface
- [`Phalcon\Contracts\Events\Manager`](/5.20/api/phalcon_contracts/#contractseventsmanager)
- **`Phalcon\Events\ManagerInterface`**
`Phalcon\Contracts\Events\Manager`
## Events\Traits\EventsAwareTrait
Trait
- **`Phalcon\Events\Traits\EventsAwareTrait`**
`Phalcon\Events\Exception` · `Phalcon\Events\ManagerInterface`
[`Phalcon\Application\AbstractApplication`](/5.20/api/phalcon_application/#applicationabstractapplication) · [`Phalcon\Auth\Guard\AbstractGuard`](/5.20/api/phalcon_auth/#authguardabstractguard) · [`Phalcon\Autoload\Loader`](/5.20/api/phalcon_autoload/#autoloadloader) · [`Phalcon\Cache\AbstractCache`](/5.20/api/phalcon_cache/#cacheabstractcache) · [`Phalcon\Cli\Task`](/5.20/api/phalcon_cli/#clitask) · [`Phalcon\DataMapper\Pdo\ConnectionLocator`](/5.20/api/phalcon_datamapper/#datamapperpdoconnectionlocator) · [`Phalcon\DataMapper\Pdo\Connection\AbstractConnection`](/5.20/api/phalcon_datamapper/#datamapperpdoconnectionabstractconnection) · [`Phalcon\Dispatcher\AbstractDispatcher`](/5.20/api/phalcon_dispatcher/#dispatcherabstractdispatcher) · [`Phalcon\Http\Request`](/5.20/api/phalcon_http/#httprequest) · [`Phalcon\Http\Response`](/5.20/api/phalcon_http/#httpresponse) · [`Phalcon\Storage\Adapter\AbstractAdapter`](/5.20/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
): mixed;
```
Helper method to fire an event
Source: https://docs.phalcon.io/5.20/api/phalcon_events/index.mdx