Update to Kirby 5

Requirements

PHP

Kirby 5 requires PHP 8.2, 8.3 or 8.4. You can check your current PHP version in the system view in the Panel. If you see PHP 8.2.*, PHP 8.3.* or PHP 8.4.*, you are already good to go.

If you see PHP 7.*, PHP 8.0.* or PHP 8.1.*, you need to update your server. Most hosting providers allow changing the PHP version from the admin backend. We recommend to switch to PHP 8.3 because this version is already compatible with Kirby 4.* and will receive security updates for two more years, so you won't have to do another PHP migration until then.

Your installed plugins and your site code may be affected by breaking changes and deprecations in PHP itself. You can find out more about this in the official migration guides for PHP 8.1 to 8.2, PHP 8.2 to 8.3 and PHP 8.3 to 8.4.

Browser support of the Panel

The Panel in Kirby 5 supports the following modern browser versions:

Notes on licensing

Kirby Basic and Kirby Enterprise licenses include three years of free feature upgrades, which makes Kirby 5 a free upgrade for everyone with a valid Kirby 4 license. Kirby 5 will automatically detect your Basic or Enterprise license, there is nothing else you need to do.

If you have an older license (e.g. for Kirby 3), you can upgrade your license via our license hub. We offer an attractive upgrade price, no matter if you have a license for Kirby 1, Kirby 2 or Kirby 3.

For site developers

This guide highlights some key changes required when upgrading to Kirby 5. There might be further smaller breaking changes affecting your specific project. Please have a look at the full list of breaking changes.

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.

Compatible plugins

To see which of the plugins you use already support Kirby 5, have a look at this list of Kirby 5 compatible plugins.

If you are using custom private plugins, please also take a look at the notes for plugin developers.

PHP type hints

We have again added more PHP type hints throughout the system (e.g. for parameters, method return types), especially around collection classes. This strictness really reduces the risk of errors in our PHP code. As a consequence, when extending core classes, you will have to add some of these type hints to your code as well.

If you run into typing error messages, have a close look at the error message, and it will tell you which part is affected, so that you can compare it with the core code and spot what type hints need to be added.

Site controller

With Kirby 5, the site controller doesn't function only as a fallback controller anymore. Instead, the data from the site controller and the template-specific controller will be merged and passed to the template.

file.sort permission

Kirby 5 introduces a new file.sort permission. If file sorting was previously disabled via the files.update permission, the new file.sort permission has to be configured accordingly.

Reserved content fields

Kirby 5 adds additional field names that are now reserved by Kirby:

• version
• versions

If you are using these field names in your content files or for custom page/site/file/user methods, please make sure to rename those.

Refactored form classes

The new changes feature builds on a fully refactored Form package. The refactoring comes with several breaking changes and deprecations. If you have been using the Form classes for your own forms, you will need to adapt these uses. The new form documentation includes several practical examples for common use cases.

How to perform the update

Once your site code and plugins have been updated, you can update Kirby itself. Please follow our general update instructions:

• Update via download
• Update via Composer
• Update via Git
• Update via Kirby CLI

For plugin developers

This guide highlights some key changes required to add support for Kirby 5 to your plugin and gives you pointers to our new resources for those developing Panel plugins. Please also have a look at the list of breaking changes and deprecations.

Panel: dark theme

The Kirby 5 Panel comes with a new theme: a dark mode.

If you have been using our design theme CSS properties, your plugin should support the dark Panel theme out of the box.

If you need to make tweaks to your styling, use the light-dark() CSS function to define different colors for light and dark mode:

background: light-dark(--color-gray-150, --color-gray-850);

Removed support for Vuex

With Kirby 5's new changes version feature, we have replaced the Vuex content module and the Vuex store completely with a new panel.content module. If you have used the content store (e.g. this.$store.getters["content/values"]), you will need to adapt your code.

If your plugin uses a custom Vuex module, it will be affected by the removal of the Vuex library from Kirby's source bundle. Instead of keeping local state inside the Panel frontend, we recommend to pass all data from the backend right when it is needed. This can be done via the Fiber architecture that was originally introduced with Kirby 3.6 and extended with many more features in the last years.

Removed vuelidate from Panel

We have removed the vuelidate library in Kirby and are using native form validation. If you have made use of vuelidate's functionality in custom Panel fields, please adapt these as well.

Removed deprecated Panel wrappers <k-inside> & <k-outside>

A common incompatibility between Kirby 5 and plugins is when the plugins use the wrapper components <k-inside> or <k-outside> for their Panel plugin templates. These components were deprecated in Kirby 4 and have finally been removed in Kirby 5. Please use the new components, <k-panel-inside> and <k-panel-outside>, instead.