🚚 How to migrate to Kirby Tips & tutorials
Skip to content
    Search by Algolia

    Migration guide for plugin developers

    How to add support for Kirby 3.8 to your plugin.

    Add compatibility with the update check

    Kirby 3.8 introduces a new update check for Kirby and plugins. It works by comparing the currently installed plugin version with the one that is detected by our plugin directory.

    Note that our plugin directory currently only detects the latest plugin version from plugins that are published in GitHub repositories.

    If your plugin is hosted elsewhere, you can send a pull request to the getkirby.com repository to add a Version field to the content file of your plugin. Please note that you are responsible to update this version number if you release a plugin update.

    We plan to build a plugin hub at a later date where you can manage your plugins and update the plugin information (including the version number and security advisories) yourself. We also plan to extend the automatic version detection for other repo hosting providers and custom endpoints. At the moment we cannot promise when these features will be ready.

    To support the update check in your plugin, please ensure that the following requirements are met:

    Ensure that the plugin name matches the plugin directory

    Every published plugin has a path in the plugin directory like https://getkirby.com/plugins/<vendor>/<plugin>. This path needs to match your plugin name in index.php (call to Kirby::plugin()). Otherwise the update check will trigger an error.

    Example: If you use Kirby::plugin('superwoman/superplugin'), the update check expects the plugin data at https://getkirby.com/plugins/superwoman/superplugin.

    If the plugin name does not match the path in the plugin directory, you have two options:

    • Either you change the plugin name in index.php. This especially makes sense if your plugin name currently contains a kirby prefix (like superwoman/kirby-superplugin). Because it's obvious within the Kirby ecosystem that your plugin is for Kirby, we recommend to remove that prefix.
    • If you don't want to or can't change your plugin name, you can send a pull request to the getkirby.com repository or let us know so we can update the plugin directory to match your existing plugin name.

    Which option makes sense for your plugin depends on your particular case. For example if your plugin contains plugin options, changing the plugin name would be a breaking change. In this case, we recommend to update the plugin directory instead.

    Note that the plugin name in index.php is independent from the Composer package name (i.e. you can continue to use a different Composer package name like vendor/kirby-someplugin).

    Ensure that the plugin version is defined in composer.json

    The update check only works if the plugin’s current version number is set in the version field of composer.json. Otherwise the message "Could not check for updates" is displayed.

    Composer recommends to omit the version field for published Composer packages, however this only applies to packages that are only ever installed via Composer. Once your plugin is installed via ZIP download or Git submodule, Kirby can only know the current plugin version from this field. So we recommend to include it for every plugin.

    New $cache->enabled() method for cache drivers

    If your plugin provides a cache driver, please implement the new enabled() method. The method will be required in a future Kirby release. Until you implement this method, Kirby will assume that your cache driver is always enabled.

    Check if any breaking changes apply to your plugin

    We try to avoid breaking changes as much as we can. But we also put a lot of effort in keeping our technical debt in Kirby as low as possible. Sometimes such breaking changes are necessary to move forward with a clean code base.

    Kirby 3.8 is a major release and comes with deprecations and breaking changes. You can find them in the changelog. We cannot list all of these changes here as not all plugins are affected by all of these changes.

    Please read through the deprecations and breaking changes and check if you are affected. In this case, please update your plugin code for compatibility with Kirby 3.8.

    Note that your plugin will not support Kirby 3.8 if it is affected by a breaking change. In contrast, deprecated code will still work for the moment but will break in a future Kirby version.