Hook reference

Every event and filter Kestello offers to plugins and themes, with the version it appeared in. Events and filters explains how to listen to them and the deprecation policy says how long a hook keeps working once it is replaced.

Events are in the namespace shown under each name. Filter callbacks receive the value first, then the arguments in the order listed, and return the value.

Events

Accounts and sign-in

IdentityLinked

Kestello\Cms\Events\IdentityLinked, since 0.1.0.

An external sign-in identity (Google, GitHub and so on, from a plugin) was linked to a user.

Property	Type	Description
$userId	int	The user.
$provider	string	The sign-in provider, such as google.
$identityId	int	The stored identity.
$via	string	registration (a new account), profile (the user linked it) or email (linked at sign-in because the verified email matched an account).

IdentityUnlinked

Kestello\Cms\Events\IdentityUnlinked, since 0.1.0.

A user removed an external sign-in identity from their account.

Property	Type	Description
$userId	int	The user.
$provider	string	The sign-in provider.
$identityId	int	The identity that was removed.

LoginFailed

Kestello\Cms\Events\LoginFailed, since 0.1.0.

A sign-in attempt failed: an unknown account, a wrong password, an inactive account, too many attempts, or a wrong second factor.

Property	Type	Description
$identifier	string	What was typed as the username or email.
$userId	?int	The account, when it exists.
$reason	string	credentials, throttled or two_factor.
$ip	string	The client address.

PasswordChanged

Kestello\Cms\Events\PasswordChanged, since 0.1.0.

A user's password changed: by the user, by an admin, or with a reset link. Other sessions and tokens may have been signed out with it.

Property	Type	Description
$userId	int	The user.
$via	string	profile, reset or admin.
$sessionsRevoked	int	Sessions signed out.
$tokensRevoked	int	Access tokens revoked.

PasswordResetRequested

Kestello\Cms\Events\PasswordResetRequested, since 0.1.0.

A password reset link was sent. Only dispatched when the account exists, so listeners never learn about unknown addresses.

Property	Type	Description
$userId	int	The user.
$ip	string	The client address that asked.

SessionRevoked

Kestello\Cms\Events\SessionRevoked, since 0.1.0.

One of a user's sessions (devices) was signed out, or all of them except the current one.

Property	Type	Description
$userId	int	The user.
$sessionId	string	The hashed session id. With allOthers, the session that was kept.
$allOthers	bool	True when every other session was signed out.
$count	int	How many sessions were signed out.

TokenCreated

Kestello\Cms\Events\TokenCreated, since 0.1.0.

A personal access token was created. The token itself is never part of the event.

Property	Type	Description
$userId	int	The owner.
$tokenId	int	The token.
$name	string	The name the owner gave it.
$scopes	list<string>	What it may do, such as content:read.

TokenRevoked

Kestello\Cms\Events\TokenRevoked, since 0.1.0.

A personal access token was revoked, or all of a user's tokens were.

Property	Type	Description
$userId	int	The owner.
$tokenId	?int	The token, or null when all of them were revoked.

TwoFactorDisabled

Kestello\Cms\Events\TwoFactorDisabled, since 0.1.0.

A user's second factor was removed: by the user, or reset with auth:reset-2fa.

Property	Type	Description
$userId	int	The user.
$byUserId	?int	Who removed it, or null from the command line.

TwoFactorEnabled

Kestello\Cms\Events\TwoFactorEnabled, since 0.1.0.

A user finished setting up a second factor.

Property	Type	Description
$userId	int	The user.
$type	string	The kind of factor, such as totp.

UserLoggedIn

Kestello\Cms\Events\UserLoggedIn, since 0.1.0.

Someone signed in.

Property	Type	Description
$userId	int	The user.
$user	array<string, mixed>	The public user fields (never the password or tokens).
$method	string	password, or the provider for an external sign-in, followed by +totp or +recovery when a second factor was used.

UserLoggedOut

Kestello\Cms\Events\UserLoggedOut, since 0.1.0.

Someone signed out.

Property	Type	Description
$userId	?int	The user, or null when the session had already expired.

UserRegistered

Kestello\Cms\Events\UserRegistered, since 0.1.0.

A user account was created: by an admin, by email sign-up or by signing in with a provider. Not dispatched for the first admin, who is created by the installer before plugins run.

Property	Type	Description
$userId	int	The new user.
$via	string	admin, email for email sign-up, or external:<provider> for an account created at sign-in.

Background jobs

JobFailed

Kestello\Cms\Events\JobFailed, since 0.1.0.

A background job used up its attempts, or could not be built, and was moved to the failed jobs list.

Property	Type	Description
$job	string	The job class.
$queue	string	The queue it ran on.
$owner	string	core, or the plugin that pushed it, such as plugin:acme.
$exception	Throwable	The last error.

Content

EntryAssigned

Kestello\Cms\Events\EntryAssigned, since 0.1.0.

An entry was assigned to someone, or unassigned.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$assigneeId	?int	Who it is assigned to now, or null when nobody.
$userId	?int	Who assigned it.

EntryCommented

Kestello\Cms\Events\EntryCommented, since 0.1.0.

Someone left an editorial comment on an entry. Comments are only seen in the admin, never on the site.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$commentId	int	The comment.
$userId	?int	Who wrote it.

EntryPublished

Kestello\Cms\Events\EntryPublished, since 0.1.0.

An entry became visible to visitors: it was published, or a scheduled entry reached its time. It is plain data, so listeners may run in the background with #[Queued].

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$title	string	Its title.
$path	?string	Its address on the site, or null for a type without public pages.

EntryReviewed

Kestello\Cms\Events\EntryReviewed, since 0.1.0.

A reviewer decided on an entry that was in review: they published or scheduled it (approved), or sent it back to draft with a note (changes_requested). Core notifies whoever submitted it.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$title	string	Its title.
$decision	string	approved or changes_requested.
$reviewerId	?int	Who decided.
$note	?string	What the reviewer asked for, when changes were requested.

EntrySaved

Kestello\Cms\Events\EntrySaved, since 0.1.0.

An entry was created or saved through the editor, the API or a plugin using Entries. Fires once per save, after the database is updated; see EntryPublished for the moment it becomes visible.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$title	string	Its title.
$status	string	Its status after the save: draft, pending, scheduled, published or private.
$created	bool	Whether this save created it.
$userId	?int	Who saved it.

EntrySubmitted

Kestello\Cms\Events\EntrySubmitted, since 0.1.0.

An entry was submitted for review: its status became pending. Core notifies the entry's assignee, or everyone who may publish it.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$title	string	Its title.
$userId	?int	Who submitted it.

EntryTrashed

Kestello\Cms\Events\EntryTrashed, since 0.1.0.

An entry was moved to the trash. It leaves the site at once, and can be restored until the trash is emptied.

Property	Type	Description
$entryId	int	The entry.
$type	string	Its content type, such as post.
$title	string	Its title.
$userId	?int	Who trashed it.

Forms

FormSubmitted

Kestello\Cms\Events\FormSubmitted, since 0.1.0.

Someone sent a form on the site and it passed every check. It is plain data, so listeners (webhooks, a CRM, a newsletter) may run in the background with #[Queued].

Property	Type	Description
$formId	int	The form.
$submissionId	?int	The stored submission, or null when the form does not keep submissions.
$data	array<string, mixed>	Field name => value. Uploaded files are lists of {name, size, type, key}.

Models

Created

Kestello\Framework\Database\Orm\Events\Created, since 0.1.0.

After a model was inserted. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Creating

Kestello\Framework\Database\Orm\Events\Creating, since 0.1.0. Listeners can stop the ones after them.

Before a model is inserted, after saving. A listener may cancel the write. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Deleted

Kestello\Framework\Database\Orm\Events\Deleted, since 0.1.0.

After a model was deleted. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Deleting

Kestello\Framework\Database\Orm\Events\Deleting, since 0.1.0. Listeners can stop the ones after them.

Before a model is deleted (soft or for good). A listener may cancel the delete. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Restored

Kestello\Framework\Database\Orm\Events\Restored, since 0.1.0.

After a soft-deleted model was restored. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Restoring

Kestello\Framework\Database\Orm\Events\Restoring, since 0.1.0. Listeners can stop the ones after them.

Before a soft-deleted model is restored. A listener may cancel it. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Saved

Kestello\Framework\Database\Orm\Events\Saved, since 0.1.0.

After a model was inserted or updated, after created or updated. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Saving

Kestello\Framework\Database\Orm\Events\Saving, since 0.1.0. Listeners can stop the ones after them.

Before a model is inserted or updated. A listener may cancel the write. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Updated

Kestello\Framework\Database\Orm\Events\Updated, since 0.1.0.

After a model was updated. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Updating

Kestello\Framework\Database\Orm\Events\Updating, since 0.1.0. Listeners can stop the ones after them.

Before a model is updated, after saving. A listener may cancel the write. $event->model is the model.

Property	Type	Description
$model	Model	The model being written.

Notifications

NotificationFailed

Kestello\Cms\Events\NotificationFailed, since 0.1.0.

A notification could not be delivered on one channel. Other channels are tried anyway.

Property	Type	Description
$userId	?int	The recipient, or null for an address that is not a user.
$type	string	The notification type, such as core.health-alert.
$channel	string	database, mail, or a channel a plugin added.
$error	string	What went wrong.

NotificationSent

Kestello\Cms\Events\NotificationSent, since 0.1.0.

A notification was delivered on one channel.

Property	Type	Description
$userId	?int	The recipient, or null for an address that is not a user.
$type	string	The notification type.
$channel	string	database, mail, or a channel a plugin added.

System

KernelBooted

Kestello\Cms\Events\KernelBooted, since 0.1.0.

Every module, plugin and theme has booted. Dispatched once per request or command, before the request is handled.

Property	Type	Description
$console	bool	True for a command, false for a web request.
$recoveryMode	bool	True when plugins are skipped (a recovery link, or --safe).

PlatformChanged

Kestello\Cms\Platform\PlatformChanged, since 0.1.0.

The settings of a platform service (cache, sessions, queue, search) were changed or reset on the Infrastructure screen, or with platform:set or platform:reset.

Property	Type	Description
$subsystem	string	cache, session, queue, search, or a service a plugin adds.
$previousDriver	string	The driver before the change.
$driver	string	The driver now.
$changed	list<string>	The names of the options whose value changed. Secrets are named, never included.
$userId	?int	Who changed it.
$reset	bool	True when the screen's settings were removed, back to the configuration file and environment.

Filters

API

api.response.{resource}

Since 0.1.0. The value is array.

The fields of one API resource row (users, entries, media...). Add or redact fields; a result that removes keys is ignored and logged.

Argument	Description
array $row	The row being shown.
Principal $principal	Who is asking.

Accounts and sign-in

auth.can_register

Since 0.1.0. The value is bool.

Whether someone may create an account, by email sign-up or by signing in with a provider.

Argument	Description
string $email	The address the account would use. Empty when a provider shared none.
?ExternalIdentity $identity	Who is signing in with a provider, or null for email sign-up.

auth.default_role

Since 0.1.0. The value is string.

The role of an account someone creates for themselves. admin and unknown roles become user.

Argument	Description
string $email	The address the account would use. Empty when a provider shared none.
?ExternalIdentity $identity	Who is signing in with a provider, or null for email sign-up.

auth.password.errors

Since 0.1.0. The value is list.

Errors for a new password. Add your own rules; core's errors cannot be removed.

Argument	Description
string $password	The new password.
?array $user	The user, when known (username, email).

auth.redirect_after_login

Since 0.1.0. The value is string.

Where to go after signing in with a provider or finishing email sign-up. The result must stay on this site.

Argument	Description
array $user	The user who signed in.

Backups

backup.skip_tables

Since 0.1.0. The value is list.

Tables to leave out of backups, such as a large log table.

Media

media.scan

Since 0.1.0. The value is ?string.

Check an uploaded file, for example with a virus scanner. Return a message to reject the upload.

Argument	Description
array $file	filename, mime, size, path, disk and key.

Pages

page.body_open

Since 0.1.0. The value is string.

HTML right after <body> on public pages.

Argument	Description
array $data	The page props.

page.footer

Since 0.1.0. The value is string.

HTML right before </body> on public pages.

Argument	Description
array $data	The page props.

page.head

Since 0.1.0. The value is string.

HTML added to the <head> of public pages. Use the page nonce for inline scripts.

Argument	Description
array $data	The page props.

page.icons

Since 0.1.0. The value is string.

The favicon and theme colour tags of every page.

page.shared

Since 0.1.0. The value is array.

The data shared with every Vue page. It is sent to the browser, so never add secrets.

pagecache.query

Since 0.1.0. The value is list.

Query parameters that get their own page cache entry. The default is ['page'].

robots.txt

Since 0.1.0. The value is string.

The generated robots.txt.

seo.head

Since 0.1.0. The value is list.

The search and sharing tags of a page, as ['meta' or 'link', attributes] pairs. Kestello escapes the attributes.

Argument	Description
array $data	The page props.

Security

security.csp

Since 0.1.0. The value is array.

The Content Security Policy, directive name => value. Names are lowercase; values may not contain ; or line breaks.