bnomei/autoloader-for-kirby

Helper to automatically load various Kirby extensions in a plugin

4.4.0 2024-08-20 16:42 UTC

README

Release Downloads Coverage Maintainability Discord

Helper to automatically load various Kirby extensions in a plugin

Installation

composer require bnomei/autoloader-for-kirby

This package is NOT a kirby plugin

  • This is a composer package because that actually makes it easier to setup and does not mess with the loading order of extensions.
  • Being a package it also can be used not only for local plugins but also as a composer dependency within plugins published online.

Autoloading of extensions

Add the autoloader for each extension type you want once and it will register all files in subfolders correctly.

Supported Extensions

The following extensions can be autoloaded:

  • blueprints (php or yml, classes)
  • classes (php)
  • collections (php)
  • commands (php)
  • controllers (php)
  • blockModels (php)
  • pageModels (php)
  • routes (php)
  • api/routes (php)
  • userModels (php)
  • snippets (php)
  • templates (php)
  • translations (php or yml or json)

Notes

  • Loading translations from yaml or json files is added by this package and not originally part of kirby core.
  • The classes autoloader is very basic. Using a custom array with kirby's load()-helper or composers psr-4 autoloading is recommended.
  • The routes and apiRoutes autoloader is based on code from @tobimori and needs a file structure similar to Next.js see examples.
  • Blueprints loaded from classes need the kirby-blueprints plugin

Usage

After requiring it as a dependency in either your project or plugin composer.json you can use the autoload()-helper to load various extension.

/site/plugins/example/index.php

<?php

// only autoloader
Kirby::plugin('bnomei/example', autoloader(__DIR__)->toArray());
<?php

// merge autoloader with custom config
Kirby::plugin('bnomei/example', autoloader(__DIR__)->toArray([
    'options' => [
        // options
    ],
    // other extensions
]));
<?php

// optionally change some settings
/*
autoloader(__DIR__, [
    'snippets' => [
        'folder' => 'schnippschnapp',
    ],
]);
*/

autoloader(__DIR__)->classes();
// use a different folder
// autoloader(__DIR__)->classes('src');

// set each option explicitly without merging
Kirby::plugin('bnomei/example', [
    'options' => [
        // options
    ],
    'blueprints' => autoloader(__DIR__)->blueprints(),
    'collections' => autoloader(__DIR__)->collections(),
    'commands' => autoloader(__DIR__)->commands(),
    'controllers' => autoloader(__DIR__)->controllers(),
    'blockModels' => autoloader(__DIR__)->blockModels(),
    'pageModels' => autoloader(__DIR__)->pageModels(),
    'routes' => autoloader(__DIR__)->routes(),
    'userModels' => autoloader(__DIR__)->userModels(),
    'snippets' => autoloader(__DIR__)->snippets(),
    'templates' => autoloader(__DIR__)->templates(),
    'translations' => autoloader(__DIR__)->translations(),
    // other extensions
]);

Settings

The package does come with default settings to fit most usecases. But you can change them every time you call the autoloader()-helper for a different directory (aka in each plugin index.php-file).

/site/plugins/example/index.php

<?php

Kirby::plugin('bnomei/example', autoloader(__DIR__, [
        'blockModels' => [
            // mapping BlockModel class names to file names, like
            // MyCustomBlock::class => 'my.custom' (site/blueprints/blocks/my.custom.yml)
            'transform' => fn ($key) => \Bnomei\Autoloader::pascalToDotCase($key),
        ],
    ])->toArray()
);

Suggestion

This plugin works great in combination with my Kirby CLI Tool which helps you to create extension files faster.

Disclaimer

This package is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this package in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.