Update to Kirby 4

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.

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:

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.

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.

• Link field
• Color field
• Moving pages in the Panel
• Optimize images on upload
• Setting an image focus point
• Fields preview for blocks
• Custom fields in the page create dialog
• Query support for pages and files sections
• Translate i18n strings in the Panel
• Generate a QR Code

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.

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.