🚀 A new era: Kirby 4 Get to know
Skip to content

Update to Kirby 4

Learn how to upgrade a Kirby 3 project to Kirby 4.

While we try to make sure that upgrading to Kirby 4 will be rather smooth for you, there are always things that can go wrong during such a process. Please make a backup of your site in any case.

Requirements

PHP

Kirby 4 requires PHP 8.1, 8.2 or 8.3. You can check your current PHP version in the system view in the Panel:

If you see PHP 8.1.*, PHP 8.2.* or PHP 8.3.*, you are already good to go.

If you see PHP 7.* or PHP 8.0.*, 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.2 because this version is already compatible with Kirby 3.9 and will receive security updates for two more years, so you won't have to do another PHP migration until then.

Before you change the PHP version in production, please ensure that your site code is already compatible with the new PHP version.

In any case, we recommend to change the PHP version on a testing or staging server first and verify that everything still works as expected. Performing the PHP update before the Kirby update to 4.0 will make the migration easier.

Kirby has supported PHP 8.1 since Kirby 3.6.1 and PHP 8.2 since Kirby 3.9.0. So updating your PHP version won't break the Kirby core if you are using a Kirby version that is newer than that.

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

Browser support of the Panel

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

Desktop Mobile
  • Firefox 110+
  • Chrome 106+
  • Safari 15+
  • Edge 106+
  • Opera 94+
  • Mobile Safari 15+
  • Android Browser 117+
  • Chrome for Android 117+

License upgrade

Kirby 4 is a major release and requires a license upgrade. Licenses for Kirby 4+ include free feature updates for three years from the time of activation.

All Kirby 3 licenses not activated before Jan 1, 2023 can be upgraded to the new licensing model for free.

For everyone else, we offer an attractive upgrade price, no matter if you have a license for Kirby 1, Kirby 2 or Kirby 3.

You can perform the upgrade directly from the Kirby 4 Panel of your site or via our license hub.

For site developers

This guide highlights some key changes required when upgrading to Kirby 4. 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.

Note that the update to Kirby 4.0 will not be successful if your site is affected by a breaking change. In contrast, deprecated code will still work for the moment but will break in a future Kirby version.

Compatible plugins

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

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

Core features replacing plugins

Kirby 4 contains some features out of the box that were previously provided by plugins. For some websites, this allows you to remove the plugin and rely solely on the native feature. Please check carefully whether the core function really covers the full scope of what your project needs. Otherwise, sticking with the plugin might still be necessary.

PHP type hints

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

A common example for an error you might see with your v3 code in v4 is

Declaration of BlogPage::children() must be compatible with Kirby\Cms\Page::children(): Kirby\Cms\Pages

What this means is that you have a custom page blog model that overwrites the default children() method, e.g.

class BlogPage extends Page
{
    public function children()
    {
        // ...
    }

What the error message is expressing is that it misses the return type for a Pages object, which we have added to the core. To fix the error message, you have to add this type hint to your code as well:

use Kirby\Cms\Pages;

class BlogPage extends Page
{
    public function children(): Pages
    {
        // ...
    }

Depending on which parts of the core code you extend in your site, you might run into similar 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.

Permissions of the almighty kirby user

$kirby->impersonate('kirby')

In v3, the almighty kirby user wasn't that almighty but still restricted by the permissions of the admin role. In v4, it is truly almighty and not bound to any restrictions. Use where needed with caution.

New core file method and reserved files field

Kirby 4 adds a new core file method: $file->manipulate(). This means that you can no longer use this method name for custom file methods. Also, the focus field name is now reserved by Kirby for file meta data. If you are using this field name in your file meta data or for custom file methods, please need to rename those files or methods.

Users field

The users field doesn't automatically use the current user as default anymore. Add default: true to keep this functionality:

author:
  type: users
  default: true

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.

For plugin developers

This guide highlights some key changes required to add support for Kirby 4 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.

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.

Note that your plugin will not support Kirby 4.0 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.

Panel: new look

The v4 Panel comes with a fresh look. Using core UI components in your plugins will help to automatically adapt your plugins to this new look. But we have also opened up our design system, so you can make use of it as we do.

We have also replaced our icon set with the open-source Remix Icon library. If your plugin uses custom icons, check if Kirby now ships with icons that fit your use case. Kirby doesn't ship the full Remix set, so you may also want to take a look at their site and pick new icons from there that fit with the rest of Kirby's new icons.

UI docs and lab

The Panel UI components have been a pain point in v3 as they were often undocumented and unstable. Kirby takes a big step here by introducing live Panel UI docs as well as a Lab with many examples how to use the components. This has helped us mature our components and will allow us to handle breaking changes of UI components with the same caution as we have already treated them in the PHP backend.

When migrating from v3 to v4 with your plugins, you might encounter situations where previous usage of UI components broke. Please take a look at the Lab examples and feel free to reach out to the team to set them up for v4.

New panel JavaScript API

We added a new Panel JavaScript API that gives you access to the most important Panel features: Control dialogs, drawers, notifications and more from your plugins, your custom panel.js or even the console. Explore examples of the various interfaces in the Lab.