Hooks

2.1.0 +

Requirements

Hooks are available since Kirby 2.1. Make sure to update before you use them.

Available hooks

Hook ID Passed Object(s)
panel.page.create $page
panel.page.update $page, $oldPage (*)
panel.page.delete $page
panel.page.sort $page, $oldPage (*)
panel.page.hide $page, $oldPage (*)
panel.page.move $page, $oldPage
panel.site.update $site, $oldSite (*)
panel.file.upload $file
panel.file.replace $file, $oldFile (*)
panel.file.rename $file, $oldFile
panel.file.update $file, $oldFile (*)
panel.file.sort $file, $oldFile (*)
panel.file.delete $file
panel.user.create $user
panel.user.update $user, $oldUser (*)
panel.user.delete $user
panel.avatar.upload $avatar
panel.avatar.delete $avatar

Hooks are being triggered after the event is called in the Panel.

2.3.2 +

* The second parameters for the following hooks were added in Kirby 2.3.2:

  • panel.file.sort
  • panel.file.replace
  • panel.file.update
  • panel.page.sort
  • panel.page.hide
  • panel.page.update
  • panel.site.update
  • panel.user.update

Registering a hook

A hook can be registered in a plugin file or in your site/config/config.php:

kirby()->hook('panel.page.create', function($page) {
  // your hook code
});

A hook is not expected to return anything. You cannot control the user flow with hooks at this state. They are silently triggered.

2.3.2 +

If multiple hooks use the same callback, you can set them at once:

kirby()->hook(['panel.page.create', 'panel.page.update'], function($page) {
  // your hook code
});

2.4.0 +

Since Kirby 2.4, you can listen to all hooks that match a specific pattern. Let's match all Panel page hooks:

kirby()->hook('panel.page.*', function($page, $oldPage = null) {
  var_dump($this->type()); // panel.page.update
});

As you can see, $this is the event object. Its type() method contains the exact event that occured.

Accessing panel, kirby, site and user in a hook callback

In a lot of use-cases it will be helpful or even necessary to access the kirby, panel, site and current user objects from within a hook callback. You can do that with the following methods:

$panel = panel();
$kirby = kirby();
$site  = site();
$user  = site()->user();

2.4.0 +

Since Kirby 2.4, $this is a new event object that contains the information as well:

kirby()->hook('panel.page.*', function($page, $oldPage = null) {
  $panel    = $this->panel();
  $kirby    = $this->kirby();
  $site     = $this->site();
  $user     = $this->user();
  $username = $this->username();
  $role     = $this->role();
});