Skip to content

Breaking changes

Breaking changes in minor releases? 3.6 is not a minor release. We follow the pattern {generation.major.minor.patch} is the 6th major release for Kirby 3 and it's a really big and important step. We don't take breaking changes lightly but they sometimes have to happen in order to keep moving forward.

Easing the pain

We know that breaking changes suck, when they break your plugins or other parts of your sites. Here's our plan how to ease your pain:

  • We will provide a tool to check for breaking changes in your installation.
  • We've created aliases for changed classes that will be removed in later releases to give you a transition time.
  • Where possible, we will try to help plugin developers with pull requests to migrate their plugins.


Deprecated code that has been removed with 3.6.0

Removed Use instead
Kirby\Cms\App::setLocale() Kirby\Toolkit\Locale::set()
Kirby\Cms\Asset::alt() -
Kirby\Cms\Page::sort() Kirby\Cms\Page::changeSort()
Kirby\Cms\KirbyTags::$tagClass You cannot set the class for KirbyTag objects to be created via KirbyTags::parse() anymore.
GET pages/(:any)/children/blueprints GET pages/(:any)/blueprints
GET site/children/blueprints GET site/blueprints

Further breaking changes

  • Multi-language setup: slugs in content files of the default language will be ignored. The folder names decide the slugs for the default language.
  • Html::encode(): Single quotes now are also converted
  • Kirby\Image\Image::__toString() returns the HTML <img> tag instead of the root string
  • File hooks: the $upload parameter is now a Kirby\Filesystem\File object, before Kirby\Image\Image
  • The video embedding helpers and methods no longer throw exceptions if the provided URL is invalid, instead null is returned.
  • Kirby\Toolkit\File::header() now returns void instead of an empty string by default
  • $files->add() and $users->add() now throw exceptions when something other than a File/User object, a Files/Users object or a file/user ID is passed to them. Empty values (null, false and true) are silently ignored. #3248
  • All API endpoints for content locking/unlocking don't display an exception anymore when content locking isn't supported.
  • Some argument and property types are now more specific and therefore stricter #3282, #3241
  • F::niceSize() doesn't check anymore whether file exists


For all users

  • New minimum browser requirements (browsers with native ESM support):
    • Firefox 60+
    • Chrome 61+,
    • Opera 48+
    • macOS Safari 11+
    • Android Browser 81+
    • Chrome for Android 88+
  • Direct URLs for tabs have changed, e.g. now /panel/site/?tab=yourTabName
  • Direct URLs for the users view have changed, e.g. now /panel/users/?role=yourRole

Custom Panel views

  • Using custom Panel views (incl. routing, breadcrumbs...) in plugins has changed fundamentally. You will have to use the new Panel areas feature now.
  • Accordingly, the frontend extension panel.plugin({ view: [...] }) has been removed. Use Panel areas instead.
  • If you have modified the ->panel*() in custom models, you now need to return a custom Panel model (based on Kirby\Panel\Model) at $page->panel() which then takes care of all Panel-related functions, e.g. if you had customized $page->panelImage() you need a custom Kirby\Panel\Page to then customize $page->panel()->image().
  • Use $model->panel()->image() instead of $model->panel()->icon()
  • $model->panel()->image() doesn't return cards and list keys anymore. Instead, src and srcset keys at the top level that correspond to the new $layout parameter.

Vue component changes

Removed Use instead
k-app k-inside (authenticated) or k-outside (unauthenticated)
k-cards k-items with layout: cards
k-card k-item with layout: cards
k-list k-items with layout: list
k-list-item k-item with layout: list
k-browser-view -
k-custom-view -
  • Removed icon prop from k-card and k-list-item. Pass data as part of the image prop instead.
  • If the cover option is not defined for a section, it is disabled by default #3226

Helpers & libraries

  • vue-router has been completely removed, use Panel areas to define custom Panel routes
  • Changes in the Vuex store and store modules
    • content module doesn't handle content locking information anymore. This in now provided directly to the model views.
    • language module has been removed, use this.$language and this.$languages instead.
    • system module has been removed, use this.$system instead.
    • translation module has been removed, use this.$translation instead.
    • user module has been removed, use this.$user instead.
    • $store.dispatch('breadcrumb') and $store.dispatch('title')have been removed. Use Panel areas instead.
  • The previewThumb helper has been removed. k-item-image takes care of processing the image data correctly inside k-item.
  • The following methods from vuex-i18n are no longer available in the new custom implementation: $tc, $tlang, $i18n.localeExists, $i18n.keyExists. Translation strings cannot be added dynamically anymore, only through our official extension.

CSS Selectors

  • .k-panel[data-translation] is now .k-panel[data-language]
  • .k-panel[data-default-translation] is now .k-panel[data-default-translation]
  • CSS class .k-block-handle has been replaced with .k-sort-handle