Breaking changes

Core

General

• Removed support for PHP 8.2. Use PHP 8.3, 8.4 or 8.5 instead. #7372
• Changed the default YAML handler to Symfony YAML which sometimes enforces a stricter syntax than our previous Spyc handler. You can switch back to Spyc with the config option 'yaml.handler' => 'spyc' #7530
• New global helper functions push(), endpush() and stack() can collide with functions of the same name in your code #7867
• Template data must not include variables named $slot or $slots. #7599
• video KirbyTag: Removed style option to protect against style injections. If you need to define a custom style attribute, please extend as a custom KirbyTag. Thanks to Peter Levashov (@petersevera) for his responsible disclosure and suggestion.
• Custom validators cannot overwrite default validators from the Kirby\Toolkit\V class any longer. #7674
• Removed Kirby\Cms\Api class. Use Kirby\Api\Api class instead. #7532
• Removed Kirby\Cms\System::php() #7816
• Kirby\Cms\App::models() and Kirby\Uuid\Uuid::index() generators are now keyed by id
• Kirby\Cms\LazyCollection::getIterator() skips items that failed hydration
• Kirby\Cms\Fields extends Kirby\Cms\Collection and Kirby\Cms\HasSiblings relies on Kirby\Cms\Collection, not Kirby\Toolkit\Collection
• Kirby\Cms\Fieldset::name() falls back to a labelized type
• Added abstract Kirby\Cms\ModelWithContent::apiUrl() method
• Kirby\Data\Txt::encodeValue() encodes true and false as 'true' and 'false' instead of '1' and '0', and an empty array as empty string instead of []
• Kirby\Http\VolatileHeaders::append() requires an array as third parameter
• Kirby\Toolkit\Str::float() returns null instead of '0' for non-numeric values (including null and ''). Use Kirby\Toolkit\Str::float($value) ?? '0' if you relied on the old behavior. #8534
• Removed command, keygen and param from Kirby\Toolkit\Html::$voidList, as they are obsolete and no longer part of the WHATWG list of void elements. Kirby\Toolkit\Html::isVoid() returns false for them and Kirby\Toolkit\Html::tag() no longer renders them self-closing. #8286
• qr() helper only accepts a site, page or file object or a URL string as parameter.
• Kirby\Cms\Language::isLast() checks the language's position in the languages collection, like isLast() for other models. Use the new Kirby\Cms\Language::isLastLanguage() to check if it is the only remaining language. #8582

Cookies & HTTP

• Cookies are signed with HMAC-SHA256 instead of HMAC-SHA1. Cookies signed by earlier versions, including the session cookie, are no longer accepted: users need to log in again after the upgrade. #8561
• Kirby\Http\Cookie::set() sets the secure option to true on HTTPS requests by default. Pass 'secure' => false if a cookie set on an HTTPS page must also be readable on plain HTTP pages: Cookie::set('name', 'value', ['secure' => false]) #8560
• The $pretty argument of Kirby\Http\Response::json() must be a bool. Pass false instead of null. #8562

MIME types

Kirby\Filesystem\Mime::fromExtension() and Kirby\Filesystem\Mime::type() return the registered IANA type for these extensions now (e.g. RFC 6713 for gzip, RFC 9239 for JavaScript, RFC 7303 for XML). #8284

Kirby\Filesystem\Mime::toExtension() returns different results for MIME types whose secondary mapping was removed:

Field methods

• Calling non-existing field methods throws a Kirby\Exception\BadMethodCallException. #7082
• Removed Kirby\Content\Field::$aliases, Kirby\Cms\Core::fieldMethods() and Kirby\Cms\Core::fieldMethodsAliases(). #7082

UUIDs

• Kirby\Uuid\Uuid::for() does not resolve any permalinks anymore. Use Kirby\Uuid\Permalink::from() instead. #7545
• Kirby\Uuid\Uuid::for() cannot be called any longer with a string. Use Kirby\Uuid\Uuid::from(string $uuid) or Kirby\Uuid\Permalink::from(string $permalink) instead. #7544
• Removed deprecated Kirby\Uuid\Uuid::url(). Use Kirby\Uuid\Uuid::toPermalink() instead.

Queries

• Removed the legacy query runner. If your config sets query.runner to legacy, remove that option. Queries always use the AST-based Kirby\Query\Runners\DefaultRunner now. #7791 #8554
• Removed Kirby\Query\Argument, Kirby\Query\Arguments, Kirby\Query\Expression, Kirby\Query\Segment and Kirby\Query\Segments. Use Kirby\Query\Query::resolve() or a custom Kirby\Query\Runners\Runner instead. #8554
• Kirby\Query\Visitors\Visitor: required methods are abstract now and get enforced when extending the class. Kirby\Query\Visitors\Visitor::coalescence(), Kirby\Query\Visitors\Visitor::logical() and Kirby\Query\Visitors\Visitor::ternary() receive the right operand/branches as Closure. #8576

Sessions

• Merged Kirby\Session\AutoSession into Kirby\Session\Sessions #8248
• Kirby\Session\Sessions::get() no longer accepts a $token. Use Kirby\Session\Sessions::find() instead. #8248
• new Kirby\Session\Sessions() no longer accepts an $options argument. Use Kirby\Session\Sessions::factory() instead. #8248
• Kirby\Session\Session no longer serializes objects

Exceptions

• Passing a single array argument to Kirby\Exception\Exception is no longer supported. Use named arguments instead. The string shorthand new Exception('Some message') is unchanged. #8459
• Removed Kirby\Exception\Exception::isTranslated() #8459

Permissions

• Several i18n error keys and strings have changed #8364
• Kirby\Cms\Permissions::for() allows null as default #8369
• Removed Kirby\Cms\ModelPermissions::canFromCache(). Use $model->guards()->isAvailable() instead. #8481

Forms

Custom fields

• Custom fields can no longer be defined as arrays. Create a class based on Kirby\Form\Field (or one of the Kirby\Form\Field\* classes) and register it by its class name. To extend a core field, extend its class (e.g. Kirby\Form\Field\TextField). #8395 #8396
• Removed Kirby\Form\FieldClass and the legacy-* fields. Kirby\Form\Field has been fully rewritten as base class for all fields. It has a new Kirby\Form\Field::id() method and implements Stringable. #8395 #8399
• Removed the Kirby\Form\Mixin\Value mixin in favor of the new Kirby\Form\Field\ValueField base class. Custom fields with a value must extend Kirby\Form\Field\ValueField (or Kirby\Form\Field\InputField), as the now final Kirby\Form\Field::hasValue() checks for it. The deprecated Kirby\Form\Mixin\Value::data() and Kirby\Form\Mixin\Value::save() methods are replaced by Kirby\Form\Field\ValueField::toStoredValue() and Kirby\Form\Field::hasValue(). #8400 #8401
• Fields with subfields must implement the new Kirby\Form\Interface\ProvidesNestedForm interface to be found by nested lookups like Kirby\Form\Fields::findByKeyRecursive('parent+child') #8401
• Field options are no longer constructor parameters. Declare each option as a property with the #[Kirby\Reflection\Attributes\Prop] attribute instead. A custom constructor must accept all other options as mixed ...$args and pass them on to parent::__construct(...$args), otherwise Kirby\Form\Field::resolve() throws an exception. #8492 #8616 #8620
• Kirby\Form\Field::factory() has been removed. Create fields with new, e.g. with the class from Kirby\Form\Field::resolve($type): new $class(...$props) #8620
• Field props are stored as passed: all setters of field classes and mixins have been removed (set the properties directly), and defaults, translations (after, before, empty, help, label, placeholder) and the lower-casing of the name are applied in the getters instead. This keeps the originally passed values accessible and reduces the work done on instantiation.
• The model and siblings of a field are passed to the constructor as model and siblings arguments and can't be changed afterwards. There are no setModel() and setSiblings() methods. An initial value can be passed as value argument and is filled after all other props are set. #8620 #8621
• files, pages and users are no longer registered field types. They still work in blueprints and are mapped to filepicker, pagepicker and userpicker. Code that looks up a field class in Kirby\Form\Field::$types must use the new names. #8622
• Fields define their API routes in Kirby\Form\Field::api(), not in a routes() method
• Removed Kirby\Cms\Picker, Kirby\Cms\PagePicker, Kirby\Cms\FilePicker and Kirby\Cms\UserPicker. Use Kirby\Panel\Controller\Dialog\ModelPickerDialogController, Kirby\Panel\Controller\Dialog\PagePickerDialogController, Kirby\Panel\Controller\Dialog\FilePickerDialogController and Kirby\Panel\Controller\Dialog\UserPickerDialogController instead. #8395

Form class

• Removed deprecated Kirby\Form\Form methods #8400
  • Kirby\Form\Form::content() → Kirby\Form\Form::toStoredValues()
  • Kirby\Form\Form::data() and Kirby\Form\Form::strings() → Kirby\Form\Form::toStoredValues() together with Kirby\Form\Form::fill(defaults: true)
  • Kirby\Form\Form::values() → Kirby\Form\Form::toFormValues()
• Kirby\Form\Form::for() and new Kirby\Form\Form() require named arguments. A $props array is no longer accepted. #8400
• Kirby\Form\Fields::validate() and Kirby\Form\Form::validate() throw the more specific Kirby\Exception\FormValidationException. #7769

Field behavior

• The checkboxes, color, multiselect, radio, select, tags and toggles fields no longer remove invalid values on submit or fill, but use the option validator to warn about them. This is in line with other input fields and has massive performance benefits. It also means that you can deliberately store a non-existing option if you skip validation.

• The api and query options of these fields are no longer available. Queries and API calls to fetch options have to be declared directly in the options property:

  fields:
    myRadio:
      type: radio
      options:
        type: query
        query: some.query
  
    myOtherRadio:
      type: radio
      options:
        type: api
        url: /some/options/api

• Kirby\Form\Field\NumberField::toNumber() and Kirby\Form\Field\RangeField::toNumber() return null instead of an empty string for empty values

• The text field no longer sets the spellcheck attribute by default

• The filepicker, pagepicker and userpicker fields only exchange UUIDs/IDs with the backend and their picker dialog, instead of full item objects with display data

Blueprints

• Removed blueprint presets (preset: page, preset: pages, preset: files). Define the layout directly with fields like pagelist and filelist instead. #8386
• Kirby\Blueprint\Blueprint::factory() requires the $model as first argument. Some blueprint props are translated lazily, so prefer Kirby\Blueprint\Blueprint::factory() over Kirby\Blueprint\Blueprint::load().
• Kirby\Blueprint\Blueprint::tab() returns a Kirby\Blueprint\Tab object and Kirby\Blueprint\Blueprint::tabs() returns a Kirby\Blueprint\Tabs collection. The normalized tabs no longer contain their link, which is built by the Kirby\Blueprint\Tab class instead. #8449
• The $inSection argument of Kirby\Blueprint\AcceptRules::fileTemplates(), Kirby\Blueprint\Blueprint::acceptedFileTemplates() and Kirby\Cms\File::blueprints() has been renamed to $inField #8406
• Removed the Kirby\Blueprint\Blueprint::$fileTemplates property and the protected methods Kirby\Blueprint\Blueprint::acceptedFileTemplatesFromFields(), Kirby\Blueprint\Blueprint::acceptedFileTemplatesFromFieldsets() and Kirby\Blueprint\Blueprint::acceptedFileTemplatesFromFieldUploads() #7829

Changed return types

HtmlString refers to Kirby\Toolkit\HtmlString #8344. Cast it with (string) if you need the raw string, and compare arrays that contain it with ==/assertEquals() instead of ===/assertSame(). The array returned by Kirby\Form\Field\ToggleField::text() contains Kirby\Toolkit\HtmlString entries, and Kirby\Toolkit\HasI18n::i18n() passes a Kirby\Toolkit\HtmlString $key through unchanged.

Changed exceptions

#8277 #8364

Methods that newly throw

Sections

Sections have been replaced by fields (see "Sections become fields" above). Blueprints with fields, files, info, pages and stats sections keep working, as they are converted to fields automatically. Everything else around sections has been removed. #8449

• Any other section type, including custom sections from plugins, is no longer supported in blueprints
• Removed the sections plugin extension, along with Kirby\Cms\App::extendSections(), Kirby\Cms\Core::sections(), Kirby\Cms\Core::sectionMixins(), Kirby\Cms\Loader::sections() and Kirby\Cms\Loader::section()
• Removed Kirby\Blueprint\Section, the Kirby\Cms\Section alias, Kirby\Blueprint\Blueprint::section(), Kirby\Blueprint\Blueprint::sections() and Kirby\Api\Api::sectionApi()
• Removed all …/sections/(:any) and …/sections/(:any)/(:all?) API routes for the site, pages, users and their files
• Removed all section dialog and drawer routes and their Panel controller classes
• The blueprints API endpoints (/api/site/blueprints, /api/pages/(:any)/blueprints and /api/users/(:any)/blueprints) accept a field query parameter instead of section. The section argument of panel.api.pages.blueprints() and panel.api.users.blueprints() has been renamed to field as well.
• Removed components: <k-sections>, <k-fields-section>, <k-files-section>, <k-info-section>, <k-models-section>, <k-pages-section> and <k-stats-section>, as well as the k-section-field adapter and the section plugin mixin. Use <k-model-form> instead of <k-sections> and <k-fields-section>.
• The endpoints object of field components no longer contains a section endpoint
• The section.loaded event has been replaced by field.loaded, emitted by pagelist and filelist fields #8415
• Renamed i18n keys
  • error.section.files.* → error.field.filelist.*
  • error.section.pages.* → error.field.pagelist.*
  • error.page.move.noSections → error.page.move.noBlueprints
• Removed i18n keys: error.section.notLoaded, error.section.type.invalid

Panel

General

• The Panel needs Chrome 124, Edge 124, Firefox 125, Safari 17.5 or newer, i.e. browsers released from roughly mid-2024 onwards. Kirby follows Baseline "widely available": we only rely on web platform features that have been in every major browser for at least 30 months. #8450
• panel.favicon option: Use href instead of url attribute. Use rel attribute instead of passing string as key.
• Color field options text => value notation has been removed. Please rewrite your options as value => text. #7534
• media/plugins/index.css and media/plugins/index.js no longer exist. Each plugin's files are served at media/plugins/{vendor}/{name}.{hash}.css and media/plugins/{vendor}/{name}.{hash}.js instead. #8603

Frontend

• All plugins that have compiled their Vue Single File Components with Vue 2 have to recompile their SFC for Vue 3 to work with Kirby 6. Consider also the Vue 3 migration guide.

• All plugin JS files get loaded as module. Plugin scripts no longer share one scope, so a plugin can't read another plugin's top-level variables. Put shared values on window explicitly. #8603

• The icon sprite is no longer part of the Panel document. Custom icons registered by plugins keep working, but markup that references the sprite by hand (<use xlink:href="#icon-…">) needs the sprite's URL now: window.panel.urls.icons + "#icon-edit" #8445

• The Panel no longer sets a data-overlay attribute. Use :has(.k-overlay[open]) instead. #8343

• Renamed components

  • <k-dropdown-content> → <k-dropdown>. The align prop has been removed. Use align-x instead. #7535
  • <k-fiber-dialog> → <k-state-dialog>
  • <k-fiber-drawer> → <k-state-drawer>

• Removed deprecated components

  • <k-bubble>, <k-bubbles> and <k-bubbles-field-preview>. Use <k-tag>, <k-tags> and <k-tags-field-preview> instead. #7533
  • <k-settings-view-button> and <k-status-view-button>

• Changes in components

  • Radio input does not support the reset option anymore. Use the toggles input instead. #7385
  • <k-panel-menu> requires its props to be passed explicitly instead of using $panel.menu itself. #7381
  • Removed deprecated model prop from model views. Use the top-level props instead. #7463
  • <k-collection> and <k-items>: @select events pass an array of selected IDs, not a single item object #7516
  • <k-structure-drawer>: prev/next need a boolean as value, not an object anymore #7790
  • <k-item>: text and info are escaped unless they are trusted HTML. Plugins that pass pre-escaped or raw HTML strings will see the markup as visible characters. Wrap the value with $h() (frontend) or in a Kirby\Toolkit\HtmlString / $model->toSafeHtmlString() (backend). #8344
  • <k-tags> / <k-picklist-input>: an option text is only rendered as HTML if it is trusted HTML. Plain strings are escaped, and the search highlighting escapes untrusted text before adding its <b> marker. #8344
  • <k-box>: the html slot binding has been removed. <slot v-bind="{ text, html }"> is now <slot v-bind="{ text }">, where text is the resolved (possibly trusted) content. #8344
  • <k-models-field-preview>: the html prop no longer defaults to true. Model items already carry trusted HTML, so the raw rendering is preserved without the flag. #8344
  • <k-installation-view>: the DOM has been fully restructured #7876
  • <k-progress>: the <progress> element is now wrapped in a <label> #8330
  • The filepicker, pagepicker and userpicker fields use their full name in CSS classes: .k-filepicker-field, .k-pagepicker-field, .k-userpicker-field
  • image, gallery and video block previews receive the file UUID instead of full file item data

• View changes

  • Preview view: versionId parameter has been renamed to mode in view controller, buttons and Vue components #7795
  • k-login-view and components have been refactored with breaking changes #7840

• Request changes: the term “Fiber” is gone for backend requests

  • The window.fiber global has been replaced with window.panelState
  • The X-Fiber namespace in request headers has been replaced with X-Panel
  • Keys aren't prefixed with $ anymore in request responses. Use without prefix. This also affects Panel plugins reloading the Panel by defining only specific keys to be reloaded. #7365

• Helpers

  • Removed $helper.isVueComponent() #7518
  • Removed $helper.link.preview(). Use <k-pages-field-preview> or <k-files-field-preview> to render a model preview, or $helper.items("items/pages", id) / $helper.items("items/files", id) if you need the raw data. #7725 #8341
  • $helper.string.sanitizeHTML() is asynchronous now #8342
  • Removed $library.dayjs.merge()

• Removed deprecated panel.dialog.openComponent() method #7518

• panel.notification.error() no longer resolves nested errors in the state. Always throw Exceptions instead to create first-level error responses. #7782

• Removed deprecated v3 CSS properties #7825:

Backend

Moved and replaced classes and methods:

• Removed methods
  • Kirby\Panel\Model::isDisabledDropdownOption() #7425
  • Kirby\Panel\Model::toPrevNextLink() and the deprecated Kirby\Panel\Model::content() (also on Kirby\Panel\Site, Kirby\Panel\Page, Kirby\Panel\File and Kirby\Panel\User) #7480
  • fileResponse()/toFiles(), pageResponse()/toPages() and userResponse()/toUsers() of the former files, pages and users field definitions. Use Kirby\Form\Field\ModelPickerField::toItem() and Kirby\Form\Field\ModelPickerField::toFormValue() instead. #7528
  • Kirby\Panel\Plugins::url(). Use Kirby\Panel\Plugins::css() for the plugin stylesheet URLs and Kirby\Panel\Plugins::js() for the plugin script URLs. #8603
  • Kirby\Panel\Plugins::files(), Kirby\Panel\Plugins::modified(), Kirby\Panel\Plugins::read() and the Kirby\Panel\Plugins::$files property. The new Kirby\Panel\Plugins::resolve() serves each plugin's stylesheet and script on its own. #8603
• Changed methods
  • Kirby\Panel\Controller\Dialog\PageCreateDialogController is initiated with a parent model (page/site) and the available blueprints #7466 #8449
  • Kirby\Panel\Panel and Kirby\Panel\Home and their methods are non-static. Instead of Kirby\Panel\Panel::router($path), use $panel->router()?->call($path). #7394 #7407 #7409
  • Kirby\Panel\Panel::areas() returns a Kirby\Panel\Areas collection of Kirby\Panel\Area objects instead of an array. The Kirby\Panel\Menu class has been rewritten to use them. #7391 #7406
  • The argument of the Kirby\Panel\Ui\Button\ViewButtons constructor has changed #7462
  • Kirby\Panel\Ui\Button\ViewButtons::view() accepts a Kirby\Panel\Controller\View\ModelViewController as $view argument, instead of a Kirby\Panel\Model #7480
  • Kirby\Panel\Ui\Button\VersionsButton::__construct(): the $versionId parameter has been renamed to $mode #7548
  • Kirby\Panel\Assets::icons() returns the URL of the icon sprite instead of its markup #8445
• Registering field dialogs or drawers without a closure throws an exception #7512

Auth

• Custom auth challenges must be rewritten based on the redesigned Kirby\Auth\Challenge class (instead of Kirby\Cms\Auth\Challenge) #8044
• Kirby\Auth\Status replaces Kirby\Cms\Auth\Status everywhere, e.g. as return value of $auth->status(). Kirby\Cms\Auth\Status::is() and Kirby\Cms\Auth\Status::clone() have no equivalent in the new class.
• Kirby\Auth\Auth::validatePassword() and Kirby\Auth\Auth::verifyChallenge() return Kirby\Cms\User|ornull
• Kirby\Cms\Find::user() throws Kirby\Exception\UserNotFoundException
• Removed Kirby\Cms\Auth::ipHash(). Use $visitor->ip(hash: true) instead.
• Auth session format changed: kirby.challenge.code → kirby.challenge.data. In-flight challenges across the Kirby upgrade won't verify.
• Removed the translation strings login.code.label.login and login.code.label.password-reset
• Removed the login extension type of panel.plugin() (panel.plugins.login). Register your custom login UI as a normal component instead and reference it in the Kirby\Auth\Method::form() or Kirby\Auth\Challenge::form() method of your custom auth method or challenge. #8045
• Removed <k-login-form>, <k-login-code-form> and the deprecated aliases <k-login> and <k-login-code> #8045
• The Panel login routes are multi-step now: login/method/... and login/challenge/...
• The TOTP enable/disable dialogs (Kirby\Panel\UserTotpEnableDialog, Kirby\Panel\UserTotpDisableDialog and <k-totp-dialog>) have been replaced by Kirby\Panel\Controller\Drawer\UserTotpDrawerController and <k-user-totp-drawer> #7445

Deprecated classes, methods, components and options keep working for now, but will be removed in a future major version.

Core

General

Auth

Sessions

Panel

Frontend

Backend

Requirements

• Kirby 5 requires at least PHP 8.2
• Kirby 5 raises browser version requirements for the Panel:
  • Safari 16+
  • Mobile Safari 16+
  • Android Browser 126+
  • Chrome for Android 126+
  • (other browsers remain unchanged)

Core

Config options

• Closures defined for the content.salt option will no longer receive a model when generating a salt for preview authentication tokens of drafts and versions as those tokens are now only based on the URI. The salt callback instead receives null and is expected to return a fixed model-independent salt in this case. When generating a salt for a file media token, the file object is still passed as model. #6836
• The api.methodOverwrite option has been renamed to api.methodOverride
• The content.fileRedirects option is now set to false by default. This protects uploaded file originals from unauthorized downloads. If you rely on the https://example.com/some/page/file.pdf or https://example.com/some-site-file.pdf routes, you can set the option to true or to a closure to control access dynamically per file.

Controllers

• Data/variables from your site controller will now be passed to all templates #6412

Hooks

• Model action before hooks: rules get applied before and after the hook runs

Collections

• PHP type hints have been added to many collection methods. If you are extending Core classes, you might need to add the same to your own classes and methods.

Models

• Kirby\Cms\HasMethods::callMethod() is now a protected method
• Kirby\Cms\ModelWithContent::lock() will now always return a Kirby\Content\Lock object, even if the model is not currently locked. You can check for that case with ModelWithContent::lock()->isLocked()
• Kirby\Cms\ModelWithContent::version() and Kirby\Cms\ModelWithContent::versions() are no longer available as direct field accessor. You need to use $model->content()->version()/$model->content()->versions() instead if you are using a field with the name version/versions.
• Kirby\Cms\Page::modified(), Kirby\Cms\File::modifiedContent() and Kirby\Cms\User::modified() now use the current language instead of the default language.
• Old model instances (objects that already were e.g. updated and returned a new model instance) can no longer modify their content. Calling actions on these old model instances will throw an exception. Use the new model instances instead.
• All methods in *Rules classes are now marked to return void instead of a bool #6660

Content & Locking

• Removed Kirby\Cms\ContentLock and Kirby\Cms\ContentLocks as well as Kirby\Cms\App::locks()
• $kirby->contentToken() only accepts object|ornull for the $model parameter instead of mixed. #6822
• Renamed token query param for preview URLs to _token #6823

Pages

• $page::translation() returns a single translation in single language mode. It now always returns a Kirby\Content\Translation object. This is also included in the $page::toArray() method.
• Cache IDs in the pages cache now include a part for the version ID. Currently this is always .latest, e.g. home.latest.html. #6827
• Removed internal $page->isVerified() method in favor of internal $page->renderVersionFromRequest() #6829

Users

• User::create() does no longer accept null as argument.
• Users without a role in their credentials file will now receive the default role (if exists), not the visitor role anymore #6656
• Setting a name field in User::update() does no longer have any effect. Use User::changeName() instead.

Roles and Permissions

• If file sorting was previously disabled via the files.update permission, the new file.sort permission has to be configured accordingly. #6589
• Kirby\Cms\Role::admin() has been renamed to Kirby\Cms\Role::defaultAdmin() #7187
• Kirby\Cms\Role::nobody() has been renamed to Kirby\Cms\Role::defaultNobody() #7187
• Classes extending Kirby\Cms\ModelPermissions need to set their category with the const CATEGORY or static function category() instead of protected string $category and use the static user() method instead of $user and $permissions properties #6880

Media & Thumbnail generation

• Kirby\Image\Dimensions::forImage() now receives an Kirby\Image\Image object #6591
• Kirby\Image\Exif::read() is now a static method that receives an absolute path to a file #6591
• Thumb driver autoOrient option has been removed and now is always applied #6591

Plugins

• Kirby\Plugin\Plugin::license() now returns the License object instead of a simple string
• Kirby\Plugin\Plugin::toArray() includes the full license info as child array instead of a string

Forms

• Kirby\Form\Field::$formFields has been renamed to Kirby\Form\Field::$siblings
• The $formField argument in Kirby\Form\Field::factory() has been renamed to $siblings
• You can no longer pass a value to Kirby\Form\Field::isEmpty() Use Kirby\Form\Field::isEmptyValue($value) instead.
• Kirby\Form\Form::fields() does no longer return null but an empty Kirby\Form\Fields collection if there are no fields.
• Kirby\Form\Field::validate() returns an array of errors instead of void.
• Removed protected Kirby\Form\Fields::$errors, Kirby\Form\Field::$errors and Kirby\Form\FieldClass::$errors properties #7131
• The language argument in the protected internal Kirby\Form\Form::prepareForLanguage() method is no longer optional and must be a Language object. #7132
• The Kirby\Form\Form class does no longer swallow errors in field classes on construction. This could be considered a breaking change or an debugging enhancement. #7167
• When using the Kirby\Form\Form class, the disabled state of fields will no longer be overwritten on construction for secondary languages. Use Kirby\Form\Form::toProps() instead, to get the correct disabled state for each field. When using Kirby\Form\Form::toProps(), permissions will also be honored when the model cannot be updated by the user role. #7166
• Kirby\Form\Form::$values has been removed #7166
• Kirby\Form\Form::prepareFieldsForLanguage() has been removed #7166
• The structure field ::form method does no longer have a $values parameter. Use $field->form()->fill() or $field->form()->submit() instead if you want to add values to the form. #7170

Filesystem

• F::read() no longer supports requesting URLs with protocols such as http:// and https://. Please use the Remote class for this purpose. #7099
• F::read() no longer silently returns false when the file exists but is not readable. Instead it triggers a PHP "Permission denied" warning. #7099

Toolkit

• The Str::ucfirst() method no longer lowercases all but the first letter of the text, it only capitalizes the first letter. #6860
• Str::camel(), Str::camelToKebab(), Str::float(), Str::kebab(), Str::kebabToCamel(), Str::length(), Str::lower(), Str::safeTemplate(), Str::short(), Str::slug(), Str::snake(), Str::studly(), Str::substr(), Str::template(), Str::ucfirst(), Str::ucwords(), Str::unhtml(), Str::upper() and Str::widont() can no longer be called without a value argument (passing a null value still works) #6401
• Passing a single space as value to Xml::attr() won't render an empty value anymore but a single space. To render an empty value, please pass an empty string. #6803

Panel

Uploads

• Panel uploads can exceed PHP’s upload_max_filesize limit #6421. If you want to restrict the upload size, please use the file blueprint accept maxsize option

Fields

• All fields: signature is no longer available as field property when loading fields from the Panel backend #6712
• Textarea field: File drag texts in the Panel always use the file UUID, if UUIDs are not disabled #6948
• Date field: Calendar dropdown input will show Sunday now as first day of the week (depending on the user's language). If you want to enforce Monday as first day of the week, you can set the date.weekday option to 1. #6635
• Select field: empty prop was removed. Use combination of required, placeholder and default to replicate functionality #6459
• Checkbox and Toggle fields: required: true now enforces that these fields need to be checked/toggled (active state)

Custom Panel CSS

• CSS attribute selectors must be written fully qualified (e.g. [data-hidden="true"] as only [data-hidden] can start matching also elements where that attribute is false) #6109

Vue Components

• <k-form> and <k-fieldset> as well as many fields and inputs don't emit an invalid event anymore. Use native HTML invalid state of elements instead. #6099
• novalidate prop has been removed from all elements but <k-form> #6099
• Removed hasErrors methods of <k-fieldset> #6173
• <k-file-preview> got fully refactored. If you were replacing or extending it, your code likely will break. Check out the new custom file preview feature if you want to provide previews for specific files. #6578
• <k-draggable>: the move callback function is receiving an event with an altered data structure
• While <k-writer> is still included as alias for <k-writer-input>, some use cases where you accessed the <k-writer> component via the $refs of <k-writer-input> have to be adapted #6172
• <k-item>: Removed data-only-option attributes
• <k-dialog>: Removed data-has-footer attribute
• <k-toggles-input>: Removed data-disabled attribute
• <k-writer-input>: Removed data-toolbar-inline attribute
• <k-bubble>: Removed data-has-text attribute
• <k-header>: Removed data-has-buttons attribute
• <k-tag>: Removed data-has-image and data-has-toggle attributes
• <k-tree>: Removed data-has-subtree attribute

Panel JS API

• panel.view.isLocked no longer exists. Use panel.content.isLocked() instead #6515
• Vuex and the Vuex content module have been removed.
• The following dialogs no longer send dispatch events via the backend. Dispatch events relied on Vuex.
  • page.changeTitle
  • page.delete
  • page.move
  • user.delete
• The panel.api.users.changePassword() method now receives three arguments for the user ID, the new password to set and the current password of the acting user (new) #7186

API

• The PATCH: account/password and PATCH: users/$user/password API routes require an additional currentPassword parameter with the password of the acting user unless in password reset mode of the current user #7186
• Removed API routes:
  • GET: /api/(:all)/lock
  • PATCH: /api/(:all)/lock
  • DELETE: /api/(:all)/lock
  • PATCH: /api/(:all)/unlock
  • DELETE: /api/(:all)/unlock

Translations

• copy.success has been renamed to copy.success.multiple

Removed deprecated code

Core

Models

• Kirby\Panel\Model::content() is deprecated. Use Kirby\Panel\Model::versions()['changes'] instead. #7153

Plugins

• Kirby\Cms\Plugin is deprecated. Use Kirby\Plugin\Plugin instead.
• Kirby\Cms\PluginAsset is deprecated. Use Kirby\Plugin\Asset instead.
• Kirby\Cms\PluginAssets is deprecated. Use Kirby\Plugin\Assets instead.

Forms

• Kirby\Form\Field::formFields() is deprecated. Use ::siblings() instead.
• Kirby\Form\Field::data() is deprecated. Use ::toStoredValue() instead.
• Kirby\Form\Field::save() is deprecated. Use ::isSaveable() instead.
• Kirby\Form\Field::value() is deprecated. Use ::toFormValue() instead.
• Kirby\Form\FieldClass::data() is deprecated. Use ::toStoredValue() instead.
• Kirby\Form\FieldClass::save() is deprecated. Use ::isSaveable() instead.
• Kirby\Form\FieldClass::value() is deprecated. Use ::toFormValue() instead.
• Kirby\Form\Form::content() is deprecated. Use ::toStoredValues() instead. #7166
• Kirby\Form\Form::data() is deprecated. Use ::toStoredValues() instead. #7166
• Kirby\Form\Form::strings() is deprecated. Use ::toStoredValues() instead. #7166
• Kirby\Form\Form::values() is deprecated. Use ::toFormValues() instead. #7166

Exceptions

• Exception classes: passing $arg array will be removed in a future version. Use named arguments. #6618

Panel

Config options

• panel.favicon option throws deprecation warnings for url option (use href instead) and for rel key (use rel option instead)

Fields

• Color field: the text => value notation for options has been deprecated and will be removed in Kirby 6. Please rewrite your options as value => text. #6913

Custom Panel CSS

• --color-backdrop CSS property has been deprecated. Use --overlay-color-back instead #6299

Vue components

• <k-writer> will be removed in a future version. Use <k-writer-input> instead #6172
• <k-bubble>, <k-bubbles> and <k-bubbles-field-preview>. Use <k-tag>, <k-tags> and <k-tag-field-preview> instead. #6569

Panel JS API

• TextareaInput.restoreSelectionCallback() has been deprecated. Use TextareaInput.restoreSelection() instead.

Core

• Kirby 4 requires at least PHP 8.1 and supports up to PHP 8.3.
• When impersonating the almighty kirby user, any permission check will succeed even if permission has been disabled for regular admins.
• The twitter icon, KirbyTag and helper have been removed. Use the legacy plugin if you still rely on these: legacy-twitter.zip
• We have added more native PHP type hints throughout the system. When extending core classes, this might require you to update your method to include those type hints as well.
• Users field doesn't automatically use the current user as default, add default: true to keep this functionality.
• When thumb generation fails, the image API now throws an error and no longer loads the original image.
• Files: manipulate is now a core method and focus a reserved field by the core. These names are no longer available for custom file methods. Previous content fields with these names can only be accessed via e.g. $file->content()->get('manipulate').
• I18n::translate(): If $fallback is an array and neither the array $key nor the array $fallback have a matching entry for the locale, the first element of the $key array will now be returned (not anymore the one from $fallback). If $fallback is a string, it will be considered with priority over both of these.
• If overwriting the hidden field, it must return 'hidden' => true now.
• Removed deprecated DS constant. Use / instead.
• When sanitizing DOM objects (e.g. in the writer field, but not during the sanitization/validation of uploaded files), host-relative URLs that point outside the site root are now allowed as the use of the HTML <base> element is assumed for sites in a subfolder. To revert to the old, strict behavior, set Sane's allowHostRelativeUrls option to false.
• Renamed parameter of ::group() method of all collection classes to $caseInsensitive
• Errors are no longer hidden when a Response is converted to a string.
• The $translations->start() and $translations->stop() methods were no longer in use and have been removed. Content files are automatically converted by the Language class.
• $languages->codes() now returns ['default'] for single language installations.
• Kirby\Panel\Assets::custom() now returns an array.
• Kirby\Uuid\Uuid is now an abstract class, child classes need to implement the id method.
• Kirby\Uuid\Uuid::key() can now also return null if the new $generate parameter isn't passed as true and no UUID has yet been generated for the model.
• Kirby\Cms\ModelWithContent doesn't extend Kirby\Cms\Model anymore.
• Removed the ::clone() method from Kirby\Cms\Auth\Status, Kirby\Http\Uri, Kirby\Cms\FileVersion, Kirby\Filesystem\Asset, Kirby\Filesystem\File, Kirby\Image\Image, Kirby\Cms\Plugin, Kirby\Cms\Role, Kirby\Cms\StructureObject and Kirby\Cms\ContentTranslation classes
• Removed the ::hardcopy() method from Kirby\Api\Api, Kirby\Cms\Api,Kirby\Email\Email, Kirby\Email\Body, Kirby\Cms\Auth\Status, Kirby\Toolkit\Pagination, Kirby\Http\Uri, Kirby\Cms\FileVersion, Kirby\Filesystem\Asset, Kirby\Filesystem\File, Kirby\Image\Image, Kirby\Cms\Role, Kirby\Cms\StructureObject and Kirby\Cms\ContentTranslation classes
• Removed ::site() method from Kirby\Cms\Plugin, Kirby\Cms\Role and Kirby\Cms\StructureObject classes
• Removed ::kirby() method from Kirby\Cms\Role and Kirby\Cms\StructureObject classes
• Unauthenticated API and Panel calls now return a correct 401 HTTP code instead of 403.
• Registering a default block model now needs to be done with the key default, not Kirby\Cms\Block.
• new Kirby\Cms\Structure()/new Kirby\Cms\StructureObject() don't work anymore as before. Use Kirby\Cms\Structure::factory()/Kirby\Cms\StructureObject::factory() instead.
• Kirby\Cms\Items::factory() and all inheriting classes throw an exception now if malformed data is passed.
• Extending the internal $model->contentFile(), $model->contentFiles(), $model->contentFileDirectory(), $model->contentFileExtension(), $model->contentFileName(), $model->readContent() and $model->writeContent() methods in a page model will no longer have an effect as these methods are no longer called by the core. Please extend the new Kirby\Content\PlainTextContentStorageHandler class instead and return an instance of your custom class from $model->storage(). Please note that the interface of PlainTextContentStorageHandler is internal and may change in the future.
• New $isExternal argument for the Kirby\Sane\Handler::sanitize() and Kirby\Sane\Handler::validate() methods that custom Sane handlers need to implement; it allows to differentiate between strings from external files that may be accessed directly and strings that will end up directly on the page.

Panel

• Blocks: Removed keyboard shortcut to move block focus up/down
• Removed road-sign icon
• The icons circle, heart and star are now named circle-filled, heart-filled and star-filled.
• Removed this.$config.search from Panel
• Area search plugins receive two additional arguments for their query callback: $limit and $page to be used to paginate the results. They should then return an array with entries results and pagination. #5191
• <k-header> doesn't include tabs anymore by default. Use <k-tabs> separately.
• Defining the footer slot in <k-dialog> will no longer wrap the slot content in the <footer> element. This can now be more flexibly handled by using <k-dialog-footer> inside the slot.
• The form drawer no longer automatically closes on submit. This is introducing the same behaviour as in dialogs. Auto-closing might often not be the intended result of submitting the form and it's easier to close it manually in a submit handler than to re-open it again.
• this.$store.state.isLoading is no longer available. You can now use window.panel.isLoading or this.$panel.isLoading in Vue components to access the current loading state.
• this.$store.state.dialog is no longer available. Use this.$panel.dialog instead.
• Removed this.$store.state.drag, use window.panel.drag/this.$panel.drag instead.
• <k-button> , <k-link>, <k-headline> and <k-content-item> only emit the click event. For other native events, use the .native event listener modifier.
• Native events (e.g. click, dbclick) need the .native modifier now when used on <k-block> and <k-block-title>
• Need to use .native modifier for all previous event listeners on <k-box and <k-image>
• <k-pagination> doesn't support setting custom labels/titles via nextLabel, prevLabel or pageLabel
• <k-range was removed and replaced by <k-alpha-range> and <k-hue-range>.
• <k-choice> has been removed. Use <k-choice-input> instead.
• The unused theme prop has been removed from <k-choice-input>.

Removed deprecated code

• The Kirby\Form\Options, Kirby\Form\OptionsApi and Kirby\Form\OptionsQuery classes have been removed. Use Kirby\Option\Options, Kirby\Option\OptionsApi or Kirby\Option\OptionsQuery instead.
• The Kirby\Toolkit\Query class has been removed. Use Kirby\Query\Query instead.
• Passing the $slot or $slots variables to snippets was deprecated and support has now finally been removed.
• Passing an empty string as value to Xml::attr() (deprecated in Kirby 3.9) no longer omits the attribute but generates an attribute with an empty value.

Core

• Files in a plugin's assets directory are now always assumed to be public, independent of their file extension. If your plugin needs to store other files in the assets directory, please use the new assets extension to explicitly define the public assets.
• Passing a single space as value to Xml::attr() (with the intention to generate an attribute with an empty value) has been deprecated in favor of passing an empty string.
• Kirby\Cms\Model: Use Kirby\Cms\ModelWithContent instead
• Kirby\Email\Email::clone() and Kirby\Email\Body::clone()
• Page::isReadable(): Use Page::isAccessible() instead
• The name query should not be used for custom API endpoints anymore, it will be used for the Kirby QL (KQL) plugin/core implementation
• Internal $model->contentFile(), $model->contentFiles(), $model->contentFileDirectory(), $model->contentFileExtension() and $model->contentFileName() methods have been deprecated and will be removed in v5.

Panel

• Custom icons using a 16x16 viewbox have been deprecated. In an upcoming version, Kirby will only support custom icons with a 24x24 viewbox by default. If you want to continue using icons with a different viewport, please wrap them in an <svg> element with the corresponding viewBox attribute.
• Icons circle-outline, heart-outline and star-outline: Use circle, heart and star instead
• this.$events: Use this.$panel.events instead
• this.$panel.events.$on: Use this.$panel.events.on instead
• this.$panel.events.$off: Use this.$panel.events.off instead
• this.$panel.events.$emit: Use this.$panel.events.emit instead
• this.$store.dispatch("isLoading"): Use this.$panel.isLoading instead
• this.$translation: Use this.$panel.translation instead
• this.$store.dispatch("dialog"): Use this.$panel.dialog.open and this.$panel.dialog.close instead
• this.$store.dispatch("drag", drag): Use this.$panel.drag = drag instead
• k-dropdown: Use k-dropdown-content as standalone instead
• k-calendar was renamed to k-calendar-input; k-calendar is still available but only as deprecated alias.

• $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|orstring 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|orstring|ornull #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