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

    Migration guide for site developers

    What you need to know and prepare before you update your sites to Kirby 3.8.

    Update to PHP 8+

    Kirby 3.8+ requires PHP 8.0 or PHP 8.1. You can check your current PHP version in the system view in the Panel:

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

    If you see PHP 7.*, 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.1 because this version 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 PHP 8.

    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 3.8 will make the migration easier.

    Kirby has supported PHP 8.0 since Kirby 3.5.0 and PHP 8.1 since Kirby 3.6.1. 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 7.4 to 8.0 and PHP 8.0 to 8.1.

    We will add support for PHP 8.2 in an upcoming Kirby update shortly after its final release (which is planned for November 24, 2022).

    Check if any breaking changes apply to your site

    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 many only apply to a small number of sites.

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

    Note that the update to Kirby 3.8 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.

    Update your plugins

    Please ensure that all of your plugins support Kirby 3.8.

    We have prepared a list of common plugins and their support status. If one of your installed plugins is not listed, please take a look on the plugin's website or repository to see if the plugin developer has information on the support status.

    If you find that a plugin doesn't yet support Kirby 3.8, feel free to add a comment to our GitHub issue. We will add the plugin to our list and try to help the plugin developer with the necessary changes for Kirby 3.8 support.

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

    Update the .htaccess file

    This step is optional but recommended to keep your setup in sync with the recommended setup.

    We have updated Kirby's default .htaccess Apache configuration file.

    The change ensures that the server only sets the environment variable for the HTTP Authorization header if the header was sent in the request. The previous configuration set an empty environment variable in this case.

    This is the new line for .htaccess:

    SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1

    If you use a different web server than Apache, you are likely already using a correct config.

    Perform the update to Kirby 3.8

    The following migration step requires that Kirby 3.8 is installed.

    To perform the update, please (as usual):

    • replace the kirby folder with the new one (either from the ZIP download, via Composer or in the Git submodule) and
    • delete the media folder.

    We recommend to perform the update on a local development server first.

    Only update your production environment once you have completed the migration and have verified that your site works as expected.

    Generate UUIDs for all pages and files

    This step is optional but recommended for optimal reliability of your site content.

    Kirby 3.8 will generate UUIDs for existing pages and files dynamically when they are first needed. This is fine for setups where the content directory is only used on one server.

    If you need to sync the content between multiple servers (e.g. production, staging and development), we recommend to generate all UUIDs in one go. This avoids content conflicts between different UUIDs that were independently generated on different servers.

    There are two ways to generate UUIDs: