Event Hooks
Observe app lifecycle events without touching framework code.
On this page
Overview
$app->on() registers a listener and $app->emit() fires an event. Listeners are observational only: they receive typed arguments, their return values are ignored, and there is no return false to block. A listener that wants to stop something throws or redirects, like any other guard.
// Register a listener
$app->on('app.route:after', function (Page $page) use ($app) {
// observe the resolved page
});
// Sites and addons emit from a page ($app->emit() is core's)
$page->emit('order.create:after', $order);
Listeners run in registration order. Addons load before routing, so app.route:after is the earliest point where the resolved Page is available.
$app->onEmit(callable $observer) registers a separate observer, called after every listener with (string $event, string $source, float $ms). It exists for tooling such as a request timeline and is not for control flow.
Naming
Events are named domain.action:timing, such as page.update:after. The full string is matched exactly.
Sites and addons emit their own events from a page: $page->emit('order.create:after', $order). The event is prefixed with the page's view, so a site page with view shop fires shop/order.create:after and a page of the shop addon fires @shop/order.create:after. Code with no page, such as an addon's index.php, uses $app->addon('shop')->emit('order.create:after', $order). A name without a slash, such as page.update:after, is your site's own lifecycle: core fires it on the site's behalf, since core never runs without a site. The slash separates the rest, so a name can't clash with those. $app->emit() is core's and throws when called from site code or an addon, so these two are the only way to emit. Each addon documents the events it emits. Listen with the full name: $app->on('@shop/order.create:after', ...).
Events
| Event | When | Args |
|---|---|---|
app.request:before |
The first event of each request, before the page is resolved | none |
app.resolve:after |
The deepest matching page has resolved, before routing | Page $page |
app.route:after |
$page->route() has resolved the routed page |
Page $page |
app.addons:after |
All addons have loaded | none |
app.exception |
A Throwable was caught while handling the request |
Throwable $e, int $code |
app.shutdown |
Once per request, as the response is sent | none |
page.controllers:after |
The page's controllers have run, just before render | Page $page |
page.render:before / page.render:after |
Around template rendering | Page $page |
page.cache:hit / page.cache:skip |
A kept page was served before routing, or a view that caches pages was not kept (string $reason) |
Page $page |
cache.get:after |
A cache lookup | string $store, ?string $path, string $key, string $result |
cache.set:after |
A cache write | string $store, ?string $path, string $key, ?int $ttl, string $result |
cache.flush:after |
A cache was emptied | string $store, string $scope |
page.create:after |
After Page::new() has saved a new page |
Page $page |
page.delete:before |
Before a page is deleted, once for each descendant and then the page | Page $page |
page.delete:after |
After a page is deleted | Page $page |
page.update:after |
After Page::save() writes |
Page $page |
page.move:after |
After a page is moved | Page $old, Page $new |
file.update:after |
After a page file is stored or its metadata updated | PageFile $file |
file.delete:after |
After a page file is deleted | string $pageUuid, string $filename |
image.save:after |
After an image variant is written | string $variantPath |
item.create:after |
After a collection item is created | Item $item |
item.update:after |
After a collection item is saved | Item $item |
item.delete:before |
Before a collection item is deleted | Item $item |
item.delete:after |
After a collection item is deleted | Item $item |
user.login:before / user.login:after |
Around a login attempt | string $username / User $user |
user.logout:before / user.logout:after |
Around logout | ?User $user / none |
user.create:after |
After a user is created | User $user |
user.update:after |
After a user is saved | User $user |
user.delete:before |
Before a user is deleted | User $user |
A create event fires once, when the new record has been saved, and carries the record as saved. Every later save fires update.
Example
Register listeners in an addon's index.php:
$app->on('app.route:after', function (Page $page) use ($app) {
// read and observe
error_log("Page resolved: {$page->title}");
// don't mutate or redirect here: that breaks the observational contract
});