The Kirby extension registry

2.3.0 +

Kirby's internal registry makes it possible to register templates, controllers, tags and more directly in your plugins. This means that you can build a full package of all kinds of plugin parts in a single directory.

Example

// site/plugins/blog/blog.php
$kirby->set('template',     'blog',     __DIR__ . '/templates/blog.php');
$kirby->set('template',     'article',  __DIR__ . '/templates/article.php');
$kirby->set('snippet',      'tagcloud', __DIR__ . '/snippets/tagcloud.php');
$kirby->set('widget',       'articles', __DIR__ . '/widgets/articles');
$kirby->set('tag',          'article',  […]);
$kirby->set('page::method', 'tags',     function() {});

As you can see in this example of a blog plugin, the plugin can take care of registering all kinds of extensions, which will then be available in templates, controllers and even in the Panel

List of registry extensions

These are all possible registry extensions you can register this way:

blueprint

// The blueprint file must exist at the given location
$kirby->set('blueprint', 'article', __DIR__ . '/blueprints/article.yml');

User blueprints can be registered like this:

$kirby->set('blueprint', 'users/admin', __DIR__ . '/blueprints/users/admin.yml');

$kirby->set('blueprint', 'fields/title', __DIR__ . '/blueprints/fields/title.yml');

$kirby->set('blueprint', ['article.text', 'article.video'], __DIR__ . '/blueprints/article.yml');

component

// Make sure that the class is defined or can be autoloaded
$kirby->set('component', 'thumb', 'MyNamespace\\MyThumbClass');

You can read more about components in How to create a core component.

controller

// The controller file must exist at the given location
$kirby->set('controller', 'blog', __DIR__ . '/controllers/blog.php');

// You can also pass a function directly
$kirby->set('controller', 'blog', function($site, $pages, $page) {
  // ...
});

$kirby->set('controller', ['blog', 'archive'], __DIR__ . '/controllers/blog.php');

field

// The directory must exist and it must have a PHP file with the same name in it
$kirby->set('field', 'myfield', __DIR__ . '/fields/myfield');

hook

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

This is an alternative syntax to kirby()->hook().

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

Extending Kirby objects

There are the following registries to extend Kirby objects:

- page::method
- pages::method
- file::method
- files::method
- site::method
- field::method

$kirby->set('page::method', 'linktag', function($page) {...});

This is an alternative syntax to directly adding the method to the object.
Learn more about extending Kirby objects.

$kirby->set('page::method', ['linktag', 'lt'], function($page) {...});

Models

There is currently only a registry for page models (page::model).

// Make sure that the class is defined or can be autoloaded
$kirby->set('page::model', 'article', 'MyNamespace\\ArticlePage');

$kirby->set('page::model', ['article.text', 'article.video'], 'MyNamespace\\ArticlePage');

option

$kirby->set('option', 'cache', true);

This is an alternative syntax to c::set(), but this syntax can be used inside plugins.

// The role file must exist at the given location
$kirby->set('role', 'client', __DIR__ . '/roles/client.php');
// You can also pass a role array directly

$kirby->set('role', 'client', [

'name' => 'Client',

'permissions' => [

...

]

]);

route

$kirby->set('route', array(
  'pattern' => 'my/awesome/url',
  'action'  => function() {
    // do something here when the URL matches the pattern above
  }
));

Learn more about routing.

snippet

// The snippet file must exist at the given location
$kirby->set('snippet', 'tagcloud', __DIR__ . '/snippets/tagcloud.php');

tag

$kirby->set('tag', 'wikipedia', array(
  'html' => function($tag) {
    return '<a href="http://wikipedia.org">Wikipedia</a>';
  }
));

This is an alternative syntax to kirbytext::$tags[$name] = $tag.
Learn more about creating custom Kirbytags.

template

// The template file must exist at the given location
$kirby->set('template', 'article', __DIR__ . '/templates/article.php');

$kirby->set('template', ['article.text', 'article.video'], __DIR__ . '/templates/article.php');

widget

// The directory must exist and it must have a PHP file with the same name in it
$kirby->set('widget', 'mywidget', __DIR__ . '/widgets/mywidget');