afbora / kirby-loader

3.0.0 2026-11-01 18:46 UTC

Requires

• php: ^8.1
• getkirby/composer-installer: ^1.2

Requires (Dev)

• getkirby/cms: ^4.3 || ^5.0 || ^6.0
• phpunit/phpunit: ^10.5 || ^11.5 || ^12.0 || ^13.0

MIT

• Ahmet Bora

• kirby4
• kirby5
• kirby6

Published on Packagist.org on 2026-11-01 18:49 UTC

README

Kirby Loader

The Kirby Loader allows you to install plugins from multiple root directories. You can easily manage plug-ins by grouping them.

Requirements

• Kirby 4.3 or newer, Kirby 5 or Kirby 6
• PHP 8.1 or newer

For Kirby 3 and Kirby 4.0 to 4.2, use version 2.

Installation

Installation with composer

composer require afbora/kirby-loader

For Kirby 3 and Kirby 4.0 to 4.2:

composer require afbora/kirby-loader:^2.3

Add as git submodule

git submodule add https://github.com/afbora/kirby-loader.git site/plugins/kirby-loader

Usage

<?php

return [
    'afbora.loader.roots' => [
        // register folders of plugins
        '/plugins/core',
        '/plugins/payment',
        '/plugins/shipping',

        // register single plugin directory
        '/theme',

        // register absolute path
        '/var/www/shared/plugins',

        // register with callback
        function () {
            return option('custom.option.path');
        },

        // callbacks can also return multiple roots
        fn () => ['/plugins/blog', '/plugins/shop'],
    ]
];

• Relative paths are relative to the index root ($kirby->root()), with or without a leading slash. Absolute paths to existing directories are used as they are.
• If a root contains an index.php, index.js or index.css file, it is loaded as a single plugin. Otherwise, every directory in the root is loaded as a plugin, like in site/plugins.
• Like in site/plugins, directories that start with _ or . are skipped. To disable a plugin, rename my-plugin to _my-plugin.
• Directories with only an index.js and/or index.css file are registered as anonymous plugins named plugins/{directory}, like in site/plugins.
• Plugin names must be unique across all roots and site/plugins. Kirby throws an error for duplicates.
• Missing roots and callbacks that return null are skipped.

Options

The default values of the package are:

Option	Default	Values	Description
afbora.loader.roots	[]	(array)	Array with the roots (strings or callbacks)

All the values can be updated in the config.php file.

Development

composer install
composer test