Breaking changes

• $kirby->impersonate() doesn't bind the app instance to the $callback closure anymore. You can access the app instance with Kirby\Cms\App::instance() or the kirby() helper. #4944
• The snippet core component receives an additional parameter bool $slots and needs to return Kirby\Template\Snippet|string for slot support. If you override the snippet component, please adapt the logic to the new core component. #4910
• $kirby->snippet() and the snippet() helper return Kirby\Template\Snippet|string|null #4910
• Html::rel() now consistently returns null instead of an empty string when no rel attribute is needed #4948
• A::missing() no longer treats an existing array key with a null value as missing #4942

Removed deprecated code

• Deprecated method Kirby\Cms\App::server() has been removed. Use Kirby\Cms\App::environment() instead. #4944

• Manually passing $slot or $slots as data variables to snippets is deprecated. In a future Kirby version, those variables will be overridden with the Slot and Slots objects. #4963
• The Toolkit\Query class has been deprecated and will be removed in a future version. Use Query\Query instead. #4944
• Passing an empty string as value to Xml::attr() / Html::attr() has been deprecated and will throw a warning. In a future version, passing an empty string won't omit the attribute anymore but render it with an empty value. To omit the attribute, please pass null. #4934
• The .k-offscreen CSS class has been deprecated. Use .sr-only instead. #4944

Panel

• The multiselect field no longer displays the option value as info #4624

Core

• Kirby 3.8.0 requires a minimum of PHP 8.0.
• uuid and permalink cannot be used as field name or custom method for any page, file, user or site anymore. Content fields can only be accessed via e.g. $model->content()->get('permalink').
• The first-level URL path @ is now blocked.
• Kirby's upload sanitizer no longer checks XML files for external links because they can be pretty common in many XML-based formats; if you want to keep the strict behavior, set Kirby\Sane\Xml::$allowedDomains = [], set this property to a custom allowlist or write a custom Sane handler for your XML-based format #4553
• Kirby now automatically loads the site/config/env.php file; if you already use this file path for a different purpose, please rename the file to a different name #4580
• A::average() returns null when passed an empty array #4649
• The default token fallback in Str::safeTemplate() changed from an empty string to null (which leaves invalid tokens in the output string). This behavior is consistent with Str::template().
• $translation->exists() now returns true for translations without an actual content file but where an content array has been provided
• The deprecated master branch of the Kirby repository was deleted. If you install Kirby via Git, e.g. as a submodule, please use the main branch instead.
• Database queries: subsequent ->where() clauses don't support passing the mode (AND|OR) as last parameter anymore, but will interpret these as actual values to filter against. Use ->andWhere() or ->orWhere() instead. #4668
• Helpers::handleErrors()'s 2nd parameter now only determines whether the error is suppressed, its 3rd parameter defines what is returned when an error is suppressed

Removed deprecated code #4478 #4515

Removed dump component. Disable dump() via KIRBY_HELPER_DUMP instead and create your own function.

PHP methods

Classes

Class Aliases

API

• $kirby->impersonate($user, $callback): The $callback will not be bound anymore to the $kirby instance in Kirby 3.9.0, $this inside the callback will refer to the current context and not $kirby instead. Using $this as $kirby inside the callback will throw a deprecation warning in debug mode. #4498
• Blueprints: The headline option for sections will be removed in a future Kirby version. Use label instead. #4515
• $kirby->server() has been deprecated and will be removed in Kirby 3.9.0. Use $kirby->environment() instead. #4515
• Kirby\Form\Options, Kirby\Form\OptionsApi, Kirby\Form\OptionsQuery have been deprecated and will be removed in Kirby 3.9. Use their Kirby\Option equivalents instead.

Composer installation

If you install Kirby using Composer, you may run into errors if your command line installation of PHP doesn’t have the extensions installed that Kirby requires. If you are sure that your web server fulfills the requirements, you can use Composer’s --ignore-platform-reqs or --ignore-platform-req=ext-* flags. #4216

Core

• Http\Router::$beforeEach and Http\Router::$afterEach aren't static anymore. Pass them in an array as second argument to the constructor instead. #4260
• Custom auth type classes in the Kirby\Http\Request\Auth\ namespace now need to be registered in the Kirby\Http\Request::$authTypes array. We also recommend to move the classes to your own namespace to avoid interference with core classes. #4264
• Field names of virtual pages' content are now converted to lowercase. If your virtual page has two fields that only differ in capitalization, only the last defined one will be available.
• The Server::hosts() method was removed. Please set the allowed URLs via the url option.
• page helper now always only returns a Kirby\Cms\Page object or null, never a pages collection. Only allows passing a single id as parameter. #4335
• pages helper now always only returns a Kirby\Cms\Pages collection or null, never single page object. #4335
• Creating a Kirby\Cms\File object requires the parent property now. #4335
• Toolkit\Str::toBytes() strictly only accepts a string as parameter now. #4335
• The $pages->children(), $pages->drafts() and $pages->index() methods no longer set the $pages->parent() object as the collection items can have multiple different parents. This can change the behaviour when finding collection items in secondary languages and when merging collections. #4105
• The dump() and e() helper function checks have been removed. If your plugins or dependencies have functions with these two names, you will get an error. You can override the conflicting functions by defining the KIRBY_HELPER_* contants. Check out how to do it.
• The second argument of the kirbytextinline() and kti() helpers has been renamed from $data to $options

Removed methods

The following deprecated methods/parts have been removed #4335

Panel

• k-block-type-table and k-structure-field have been largely refactored. If you (or a plugin) extends these, stuff might break.
• k-pages-section and k-files-section have been modified extensively #4247
• Toolkit\Html::attr([], null) now consistently returns null instead of an empty string. #4018
• Removed builder and editor field migration for blocks field.

API

The following deprecated methods/parts have been removed #4335

• The dump component was deprecated and superseded by the new feature to replace helpers (KIRBY_HELPER_DUMP constant). The component will be removed in Kirby 3.8.0. #4018
• Http\Server class will be removed in 3.8.0
• The constants in Http\Server:: are now deprecated and will be removed in 3.8.0. They are no longer needed.
• The $pages->findById() and $pages->findByUri() methods have been deprecated and will be removed in 3.8.0. If you want to directly get a page by ID, use $pages->get(). If you want the previous fuzzy behaviour that queries both by ID and URI, use $pages->find().
• The $pages->findByIdRecursive() method has been deprecated and will be removed in v3.8.0. Please use $pages->find() instead.
• The $files->findById() method has been deprecated and will be removed in v3.8.0. Please use $files->find() instead.
• The $pages->findByKey(), $files->findByKey() and $users->findByKey() methods have been marked as internal. Please use the find() methods instead.
• The $inline parameter in $kirby->kirbytext() is deprecated. Use $options['markdown']['inline'] instead.
• The $inline parameter in $kirby->markdown() is deprecated. Use $options['inline'] instead.
• Blueprint presets page, pages and files are deprecated.

Deprecation warnings

The following deprecated methods/parts throw warnings in 3.7.0 and will be removed starting in 3.8.0 #4335

Methods

API

Breaking changes in minor releases? 3.6 is not a minor release. We follow the pattern {generation.major.minor.patch}

3.6.0.0 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.

Panel

For all users

• New minimum browser requirements (browsers with native ESM and dynamic import() support):

  • Firefox 67+
  • Chrome 63+
  • Edge 79+
  • Opera 50+
  • macOS Safari 11.1+
  • Safari iOS 11+
  • Android Browser 92+
  • Chrome for Android 92+

• Several blueprint options that use the query syntax were updated to escape against raw HTML output that may lead to XSS attacks. HTML code directly in the blueprint option still works as normal. If queries need to return HTML, you can use the new {< >} syntax. In this case you need to ensure manually that the returned HTML code is safe. With the {{ }} syntax, Kirby performs the escaping for you.

# works as normal
info: "This is <strong>{{ page.important }}</strong>"

# custom site method returns HTML, new `{< >}` syntax needed
info: "via {< site.myMethodWithHtml >}"

• 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 extension now.
• Accordingly, the frontend extension panel.plugin({ view: [...] }) has been removed. Use Panel areas instead.

Kirby\Panel namespace related

• If you have modified the ->panel*() methods 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 icon prop from k-card and k-list-item. Pass data as part of the image prop instead to new k-item component.
• If the cover option is not defined for a section, it is disabled by default.
• The <k-box text="..." /> property is now rendered as plain text by default instead of as HTML code. For the previous behavior use <k-box text="..." :html="true" />.

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.
• Removed outdated $api methods in Vue:
  • $api.pages.breadcrumb
  • $api.files.breadcrumb
  • $api.users.breadcrumb
  • $api.site.breadcrumb
  • $api.site.options
  • $api.roles.options
  • $api.translations.options

CSS Selectors

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

Core

• Kirby no longer supports PHP 7.3, which will reach its end-of-life date soon. We will add support for PHP 8.1 to Kirby as soon as possible after the official release of PHP 8.1.
• Multi-language setup: slugs in content files of the default language will be ignored. The folder names decide the slugs for the default language.
• Hidden blocks in the layout field will no longer be visible (as expected)
• $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
• F::modified() does no longer calculate a maximum between mtime and ctime for file changes. This could in theory lead to different timestamps in some scenarios. Very unlikely though.
• 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
• F::niceSize() doesn't check anymore whether file exists
• The public static configuration attributes of the Sane classes have been renamed for consistency with the new Toolkit\Dom class
• The Sane\Svg::$allowedNamespaces attribute now expects namespace reference names as the array keys instead of full attribute names (so xmlns:xlink should become just xlink and xmlns should become an empty string)
• The Sane\Svg::$allowedTags attribute (before $allowedElements) now is an associative array with the allowed attributes for this tag as the value
• All API endpoints for content locking/unlocking don't display an exception anymore when content locking isn't supported.
• The crop keyword is now always present in filenames for cropped files. All center cropped files need to be regenerated.
• Cms\Collection::has(): 1st parameter got renamed to $key
• Cms\Collection::indexOf(): 1st parameter got renamed to $needle
• Cms\Collection::query(): 1st parameter got renamed to $arguments
• Some argument and property types are now more specific and therefore stricter #3282, #3241
• In multi-lang setups, calling $pages->find(), $pages->findById() or $pages->findByUri() on a non-children collection (e.g. grandchildren) with just a slug no longer works. This makes the Pages class more consistent between single and multi language setups.

Deprecated code that has been removed with 3.6.0

Removed methods

Deprecated methods

Required PHP Version

With this release we drop support for PHP 7.2, which has reached end of life. But we also introduce support for the brand-new stable version of PHP 8.0, which has been released on December 1st.

Date field format option

3.5.0 is dropping the format option of the date field. This is a breaking change which we will reverse in 3.5.1.

accept option for file blueprints

If no custom accept restrictions are defined in the file blueprint, Kirby will now limit the accepted uploads to the types image, document, archive, audio and video by default. This protects your sites against unexpected uploads like code files that could be used to attack the server or the visitor's browsers.

You can customize the accepted file types in the file blueprint.

Removed methods

Deprecated methods

To ensure proper nesting, Kirby relies on the plugin option default values defined in the plugin using the options extension. If your plugin uses a nested structure in the option defaults, the defaults need to be changed to use the dot notation.

Only options registered in that way can be set in all supported ways (dot notation, fully or partially nested) in the site config. You can read more about this in the reference.

• The pagination object is now immutable and all setters are disabled by default #1887
• The Vuex form store module in the panel has been refactored and is now called content. If your panel plugin works with the form store module, please check out the refactored module. Conversion won't be difficult. We made lots of thinks a lot cleaner. But you need to rename the actions or getters that you use from the old module.
• The v-tab directive is no longer available. Tabbable elements should use the tab mixin

Deprecated methods

• The deprecated $kirby->root('translations') root is no longer available. Use $kirby->root('i18n:translations') instead

We've also added deprecation warnings to additional core methods. You will run into an exception if the debug mode is active. You can keep those methods for now in production (with disabled debug mode), but we recommend to convert them as soon as possible. Here are the deprecated methods and how to replace them:

• File::meta (use File::content instead)
• File::rename (use File::changeName instead)
• Languages::findDefault (use Languages::default() instead)
• Page::hasInvisibleChildren (use Page::hasUnlistedChildren instead)
• Page::hasNextInvisible (use Page::hasNextUnlisted instead)
• Page::hasNextVisible (use Page::hasNextListed instead)
• Page::hasPrevInvisible (use Page::hasPrevUnlisted instead)
• Page::hasPrevVisible (use Page::hasPrevListed instead)
• Page::hasVisibleChildren (use Page::hasListedChildren instead)
• Page::nextInvisible (use Page::nextUnlisted instead)
• Page::nextVisible (use Page::nextListed instead)
• Page::prevInvisible (use Page::prevUnlisted instead)
• Page::prevVisible (use Page::prevListed instead)
• Page::isInvisible (use Page::isUnlisted instead)
• Page::isVisible (use Page::isListed instead)
• Site::hasInvisibleChildren (use Site::hasUnlistedChildren instead)
• Site::hasVisibleChildren (use Site::hasListedChildren instead)

• Translations root deprecated and will be removed in 3.3. Use i18n:translations instead
• File::model() does no longer return the parent model. Use File::parent() instead