Upgrade to 3.5.5

2021-05-11 11:55:32 +02:00
parent de3560f3d6
commit efeff45192
146 changed files with 2008 additions and 1075 deletions
--- a/kirby/src/Cms/Api.php
+++ b/kirby/src/Cms/Api.php
@@ -258,7 +258,7 @@ class Api extends BaseApi
     * Setter for the parent Kirby instance
     *
     * @param \Kirby\Cms\App $kirby
-     * @return self
+     * @return $this
     */
    protected function setKirby(App $kirby)
    {
--- a/kirby/src/Cms/App.php
+++ b/kirby/src/Cms/App.php
@@ -11,6 +11,7 @@ use Kirby\Exception\NotFoundException;
 use Kirby\Http\Request;
 use Kirby\Http\Router;
 use Kirby\Http\Server;
+use Kirby\Http\Uri;
 use Kirby\Http\Visitor;
 use Kirby\Session\AutoSession;
 use Kirby\Toolkit\A;
@@ -224,7 +225,7 @@ class App
    /**
     * Normalizes and globally sets the configured options
     *
-     * @return self
+     * @return $this
     */
    protected function bakeOptions()
    {
@@ -260,7 +261,7 @@ class App
     * Sets the directory structure
     *
     * @param array|null $roots
-     * @return self
+     * @return $this
     */
    protected function bakeRoots(array $roots = null)
    {
@@ -273,7 +274,7 @@ class App
     * Sets the Url structure
     *
     * @param array|null $urls
-     * @return self
+     * @return $this
     */
    protected function bakeUrls(array $urls = null)
    {
@@ -342,7 +343,7 @@ class App
     *
     * @param array $props
     * @param bool $setInstance If false, the instance won't be set globally
-     * @return self
+     * @return static
     */
    public function clone(array $props = [], bool $setInstance = true)
    {
@@ -609,7 +610,7 @@ class App
     *
     * @param \Kirby\Cms\App|null $instance
     * @param bool $lazy If `true`, the instance is only returned if already existing
-     * @return self|null
+     * @return static|null
     */
    public static function instance(self $instance = null, bool $lazy = false)
    {
@@ -1226,6 +1227,10 @@ class App
     */
    public function session(array $options = [])
    {
+        // never cache responses that depend on the session
+        $this->response()->cache(false);
+        $this->response()->header('Cache-Control', 'no-store', true);
+
        return $this->sessionHandler()->get($options);
    }

@@ -1244,7 +1249,7 @@ class App
     * Create your own set of languages
     *
     * @param array|null $languages
-     * @return self
+     * @return $this
     */
    protected function setLanguages(array $languages = null)
    {
@@ -1266,7 +1271,7 @@ class App
     * used for the router
     *
     * @param string|null $path
-     * @return self
+     * @return $this
     */
    protected function setPath(string $path = null)
    {
@@ -1278,7 +1283,7 @@ class App
     * Sets the request
     *
     * @param array|null $request
-     * @return self
+     * @return $this
     */
    protected function setRequest(array $request = null)
    {
@@ -1293,7 +1298,7 @@ class App
     * Create your own set of roles
     *
     * @param array|null $roles
-     * @return self
+     * @return $this
     */
    protected function setRoles(array $roles = null)
    {
@@ -1310,7 +1315,7 @@ class App
     * Sets a custom Site object
     *
     * @param \Kirby\Cms\Site|array|null $site
-     * @return self
+     * @return $this
     */
    protected function setSite($site = null)
    {
@@ -1479,11 +1484,26 @@ class App
     * Returns a system url
     *
     * @param string $type
-     * @return string
+     * @param bool $object If set to `true`, the URL is converted to an object
+     * @return string|\Kirby\Http\Uri
     */
-    public function url(string $type = 'index'): string
+    public function url(string $type = 'index', bool $object = false)
    {
-        return $this->urls->__get($type);
+        $url = $this->urls->__get($type);
+
+        if ($object === true) {
+            if (Url::isAbsolute($url)) {
+                return Url::toObject($url);
+            }
+
+            // index URL was configured without host, use the current host
+            return Uri::current([
+                'path'   => $url,
+                'query'  => null
+            ]);
+        }
+
+        return $url;
    }

    /**
--- a/kirby/src/Cms/AppErrors.php
+++ b/kirby/src/Cms/AppErrors.php
@@ -83,7 +83,7 @@ trait AppErrors
                $fatal = $this->option('fatal');

                if (is_a($fatal, 'Closure') === true) {
-                    echo $fatal($this);
+                    echo $fatal($this, $exception);
                } else {
                    include $this->root('kirby') . '/views/fatal.php';
                }
@@ -144,6 +144,7 @@ trait AppErrors
        });

        $this->setWhoopsHandler($handler);
+        $this->whoops()->sendHttpCode(false);
    }

    /**
--- a/kirby/src/Cms/AppTranslations.php
+++ b/kirby/src/Cms/AppTranslations.php
@@ -158,7 +158,8 @@ trait AppTranslations
    /**
     * Set locale settings
     *
-     * @deprecated 3.5.0 Use \Kirby\Toolkit\Locale::set() instead
+     * @deprecated 3.5.0 Use `\Kirby\Toolkit\Locale::set()` instead
+     * @todo Remove in 3.6.0
     *
     * @param string|array $locale
     */
--- a/kirby/src/Cms/Asset.php
+++ b/kirby/src/Cms/Asset.php
@@ -116,7 +116,7 @@ class Asset
     * Setter for the path
     *
     * @param string $path
-     * @return self
+     * @return $this
     */
    protected function setPath(string $path)
    {
--- a/kirby/src/Cms/Auth/EmailChallenge.php
+++ b/kirby/src/Cms/Auth/EmailChallenge.php
@@ -56,12 +56,12 @@ class EmailChallenge extends Challenge

        $kirby = $user->kirby();
        $kirby->email([
-            'from' => $kirby->option('auth.challenge.email.from', 'noreply@' . $kirby->system()->indexUrl()),
+            'from' => $kirby->option('auth.challenge.email.from', 'noreply@' . $kirby->url('index', true)->host()),
            'fromName' => $kirby->option('auth.challenge.email.fromName', $kirby->site()->title()),
            'to' => $user,
            'subject' => $kirby->option(
                'auth.challenge.email.subject',
-                I18n::translate('login.email.' . $mode . '.subject')
+                I18n::translate('login.email.' . $mode . '.subject', null, $user->language())
            ),
            'template' => 'auth/' . $mode,
            'data' => [
--- a/kirby/src/Cms/Auth/Status.php
+++ b/kirby/src/Cms/Auth/Status.php
@@ -153,7 +153,7 @@ class Status
     * Sets the type of the active challenge
     *
     * @param string|null $challenge
-     * @return self
+     * @return $this
     */
    protected function setChallenge(?string $challenge = null)
    {
@@ -166,7 +166,7 @@ class Status
     * a fallback when $challenge is `null`
     *
     * @param string|null $challengeFallback
-     * @return self
+     * @return $this
     */
    protected function setChallengeFallback(?string $challengeFallback = null)
    {
@@ -178,7 +178,7 @@ class Status
     * Sets the email address of the current/pending user
     *
     * @param string|null $email
-     * @return self
+     * @return $this
     */
    protected function setEmail(?string $email = null)
    {
@@ -190,7 +190,7 @@ class Status
     * Sets the Kirby instance for user lookup
     *
     * @param \Kirby\Cms\App $kirby
-     * @return self
+     * @return $this
     */
    protected function setKirby(App $kirby)
    {
@@ -202,7 +202,7 @@ class Status
     * Sets the authentication status
     *
     * @param string $status `active|impersonated|pending|inactive`
-     * @return self
+     * @return $this
     */
    protected function setStatus(string $status)
    {
--- a/kirby/src/Cms/Block.php
+++ b/kirby/src/Cms/Block.php
@@ -3,6 +3,7 @@
 namespace Kirby\Cms;

 use Kirby\Exception\InvalidArgumentException;
+use Kirby\Toolkit\Str;
 use Throwable;

 /**
@@ -86,6 +87,10 @@ class Block extends Item
    /**
     * Deprecated method to return the block type
     *
+     * @deprecated 3.5.0 Use `\Kirby\Cms\Block::type()` instead
+     * @todo Add deprecated() helper warning in 3.6.0
+     * @todo Remove in 3.7.0
+     *
     * @return string
     */
    public function _key(): string
@@ -96,6 +101,10 @@ class Block extends Item
    /**
     * Deprecated method to return the block id
     *
+     * @deprecated 3.5.0 Use `\Kirby\Cms\Block::id()` instead
+     * @todo Add deprecated() helper warning in 3.6.0
+     * @todo Remove in 3.7.0
+     *
     * @return string
     */
    public function _uid(): string
@@ -131,6 +140,19 @@ class Block extends Item
        ];
    }

+    /**
+     * Converts the block to HTML and then
+     * uses the Str::excerpt method to create
+     * a non-formatted, shortened excerpt from it
+     *
+     * @param mixed ...$args
+     * @return string
+     */
+    public function excerpt(...$args)
+    {
+        return Str::excerpt($this->toHtml(), ...$args);
+    }
+
    /**
     * Checks if the block is empty
     *
--- a/kirby/src/Cms/BlockConverter.php
+++ b/kirby/src/Cms/BlockConverter.php
@@ -219,7 +219,7 @@ class BlockConverter
    {
        return [
            'content' => [
-                'text' => $params['content']
+                'text' => '<p>' . $params['content'] . '</p>'
            ],
            'type' => 'text'
        ];
--- a/kirby/src/Cms/Blueprint.php
+++ b/kirby/src/Cms/Blueprint.php
@@ -219,7 +219,7 @@ class Blueprint
     * @param string $name
     * @param string|null $fallback
     * @param \Kirby\Cms\Model $model
-     * @return self
+     * @return static|null
     */
    public static function factory(string $name, string $fallback = null, Model $model)
    {
--- a/kirby/src/Cms/Collection.php
+++ b/kirby/src/Cms/Collection.php
@@ -271,7 +271,7 @@ class Collection extends BaseCollection
     * Any part of the query is optional.
     *
     * @param array $query
-     * @return self
+     * @return static
     */
    public function query(array $query = [])
    {
--- a/kirby/src/Cms/Content.php
+++ b/kirby/src/Cms/Content.php
@@ -198,7 +198,7 @@ class Content
     * passed key(s)
     *
     * @param string ...$keys
-     * @return self
+     * @return static
     */
    public function not(...$keys)
    {
@@ -227,7 +227,7 @@ class Content
     * Set the parent model
     *
     * @param \Kirby\Cms\Model $parent
-     * @return self
+     * @return $this
     */
    public function setParent(Model $parent)
    {
@@ -252,7 +252,7 @@ class Content
     *
     * @param array|null $content
     * @param bool $overwrite
-     * @return self
+     * @return $this
     */
    public function update(array $content = null, bool $overwrite = false)
    {
--- a/kirby/src/Cms/ContentTranslation.php
+++ b/kirby/src/Cms/ContentTranslation.php
@@ -163,7 +163,7 @@ class ContentTranslation

    /**
     * @param string $code
-     * @return self
+     * @return $this
     */
    protected function setCode(string $code)
    {
@@ -173,7 +173,7 @@ class ContentTranslation

    /**
     * @param array|null $content
-     * @return self
+     * @return $this
     */
    protected function setContent(array $content = null)
    {
@@ -183,7 +183,7 @@ class ContentTranslation

    /**
     * @param \Kirby\Cms\Model $parent
-     * @return self
+     * @return $this
     */
    protected function setParent(Model $parent)
    {
@@ -193,7 +193,7 @@ class ContentTranslation

    /**
     * @param string|null $slug
-     * @return self
+     * @return $this
     */
    protected function setSlug(string $slug = null)
    {
@@ -216,7 +216,7 @@ class ContentTranslation
     *
     * @param array|null $data
     * @param bool $overwrite
-     * @return self
+     * @return $this
     */
    public function update(array $data = null, bool $overwrite = false)
    {
--- a/kirby/src/Cms/Field.php
+++ b/kirby/src/Cms/Field.php
@@ -179,7 +179,7 @@ class Field
     * Provides a fallback if the field value is empty
     *
     * @param mixed $fallback
-     * @return self
+     * @return $this|static
     */
    public function or($fallback = null)
    {
--- a/kirby/src/Cms/File.php
+++ b/kirby/src/Cms/File.php
@@ -254,6 +254,8 @@ class File extends ModelWithContent
        } else {
            if ($this->type() === 'image') {
                return '(image: ' . $url . ')';
+            } elseif ($this->type() === 'video') {
+                return '(video: ' . $url . ')';
            } else {
                return '(file: ' . $url . ')';
            }
@@ -265,7 +267,7 @@ class File extends ModelWithContent
     *
     * @internal
     * @param mixed $props
-     * @return self
+     * @return static
     */
    public static function factory($props)
    {
@@ -661,7 +663,7 @@ class File extends ModelWithContent
     * Sets the Blueprint object
     *
     * @param array|null $blueprint
-     * @return self
+     * @return $this
     */
    protected function setBlueprint(array $blueprint = null)
    {
@@ -677,7 +679,7 @@ class File extends ModelWithContent
     * Sets the filename
     *
     * @param string $filename
-     * @return self
+     * @return $this
     */
    protected function setFilename(string $filename)
    {
@@ -689,7 +691,7 @@ class File extends ModelWithContent
     * Sets the parent model object
     *
     * @param \Kirby\Cms\Model|null $parent
-     * @return self
+     * @return $this
     */
    protected function setParent(Model $parent = null)
    {
@@ -702,7 +704,7 @@ class File extends ModelWithContent
     * auto root detection
     *
     * @param string|null $root
-     * @return self
+     * @return $this
     */
    protected function setRoot(string $root = null)
    {
@@ -712,7 +714,7 @@ class File extends ModelWithContent

    /**
     * @param string|null $template
-     * @return self
+     * @return $this
     */
    protected function setTemplate(string $template = null)
    {
@@ -724,7 +726,7 @@ class File extends ModelWithContent
     * Sets the url
     *
     * @param string|null $url
-     * @return self
+     * @return $this
     */
    protected function setUrl(string $url = null)
    {
--- a/kirby/src/Cms/FileActions.php
+++ b/kirby/src/Cms/FileActions.php
@@ -25,7 +25,7 @@ trait FileActions
     *
     * @param string $name
     * @param bool $sanitize
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException
     */
    public function changeName(string $name, bool $sanitize = true)
@@ -84,7 +84,7 @@ trait FileActions
     * Changes the file's sorting number in the meta file
     *
     * @param int $sort
-     * @return self
+     * @return static
     */
    public function changeSort(int $sort)
    {
@@ -161,7 +161,7 @@ trait FileActions
     * way of generating files.
     *
     * @param array $props
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\InvalidArgumentException
     * @throws \Kirby\Exception\LogicException
     */
@@ -256,7 +256,7 @@ trait FileActions
     * Move the file to the public media folder
     * if it's not already there.
     *
-     * @return self
+     * @return $this
     */
    public function publish()
    {
@@ -272,7 +272,7 @@ trait FileActions
     * source.
     *
     * @param string $source
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\LogicException
     */
    public function replace(string $source)
@@ -295,7 +295,7 @@ trait FileActions
    /**
     * Remove all public versions of this file
     *
-     * @return self
+     * @return $this
     */
    public function unpublish()
    {
--- a/kirby/src/Cms/FileFoundation.php
+++ b/kirby/src/Cms/FileFoundation.php
@@ -189,7 +189,7 @@ trait FileFoundation
     * Setter for the root
     *
     * @param string|null $root
-     * @return self
+     * @return $this
     */
    protected function setRoot(string $root = null)
    {
@@ -201,7 +201,7 @@ trait FileFoundation
     * Setter for the file url
     *
     * @param string $url
-     * @return self
+     * @return $this
     */
    protected function setUrl(string $url)
    {
--- a/kirby/src/Cms/FileVersion.php
+++ b/kirby/src/Cms/FileVersion.php
@@ -97,7 +97,7 @@ class FileVersion
     * Applies the stored modifications and
     * saves the file on disk
     *
-     * @return self
+     * @return $this
     */
    public function save()
    {
--- a/kirby/src/Cms/Files.php
+++ b/kirby/src/Cms/Files.php
@@ -31,7 +31,7 @@ class Files extends Collection
     * current collection
     *
     * @param mixed $object
-     * @return self
+     * @return $this
     */
    public function add($object)
    {
@@ -57,7 +57,7 @@ class Files extends Collection
     *
     * @param array $files List of file ids
     * @param int $offset Sorting offset
-     * @return self
+     * @return $this
     */
    public function changeSort(array $files, int $offset = 0)
    {
@@ -76,7 +76,7 @@ class Files extends Collection
     *
     * @param array $files
     * @param \Kirby\Cms\Model $parent
-     * @return self
+     * @return static
     */
    public static function factory(array $files, Model $parent)
    {
@@ -124,7 +124,7 @@ class Files extends Collection
     * Filter all files by the given template
     *
     * @param null|string|array $template
-     * @return self
+     * @return $this|static
     */
    public function template($template)
    {
--- a/kirby/src/Cms/Form.php
+++ b/kirby/src/Cms/Form.php
@@ -90,7 +90,7 @@ class Form extends BaseForm
    /**
     * @param \Kirby\Cms\Model $model
     * @param array $props
-     * @return self
+     * @return static
     */
    public static function for(Model $model, array $props = [])
    {
--- a/kirby/src/Cms/HasChildren.php
+++ b/kirby/src/Cms/HasChildren.php
@@ -213,7 +213,7 @@ trait HasChildren
     * Sets the Children collection
     *
     * @param array|null $children
-     * @return self
+     * @return $this
     */
    protected function setChildren(array $children = null)
    {
@@ -228,7 +228,7 @@ trait HasChildren
     * Sets the Drafts collection
     *
     * @param array|null $drafts
-     * @return self
+     * @return $this
     */
    protected function setDrafts(array $drafts = null)
    {
--- a/kirby/src/Cms/HasFiles.php
+++ b/kirby/src/Cms/HasFiles.php
@@ -203,7 +203,7 @@ trait HasFiles
     * Sets the Files collection
     *
     * @param \Kirby\Cms\Files|null $files
-     * @return self
+     * @return $this
     */
    protected function setFiles(array $files = null)
    {
--- a/kirby/src/Cms/Ingredients.php
+++ b/kirby/src/Cms/Ingredients.php
@@ -70,7 +70,7 @@ class Ingredients
     *
     * @internal
     * @param array $ingredients
-     * @return self
+     * @return static
     */
    public static function bake(array $ingredients)
    {
--- a/kirby/src/Cms/Language.php
+++ b/kirby/src/Cms/Language.php
@@ -197,7 +197,7 @@ class Language extends Model
     *
     * @internal
     * @param array $props
-     * @return self
+     * @return static
     */
    public static function create(array $props)
    {
@@ -445,7 +445,7 @@ class Language extends Model
     * Saves the language settings in the languages folder
     *
     * @internal
-     * @return self
+     * @return $this
     */
    public function save()
    {
@@ -476,7 +476,7 @@ class Language extends Model

    /**
     * @param string $code
-     * @return self
+     * @return $this
     */
    protected function setCode(string $code)
    {
@@ -486,7 +486,7 @@ class Language extends Model

    /**
     * @param bool $default
-     * @return self
+     * @return $this
     */
    protected function setDefault(bool $default = false)
    {
@@ -496,7 +496,7 @@ class Language extends Model

    /**
     * @param string $direction
-     * @return self
+     * @return $this
     */
    protected function setDirection(string $direction = 'ltr')
    {
@@ -506,7 +506,7 @@ class Language extends Model

    /**
     * @param string|array $locale
-     * @return self
+     * @return $this
     */
    protected function setLocale($locale = null)
    {
@@ -521,7 +521,7 @@ class Language extends Model

    /**
     * @param string $name
-     * @return self
+     * @return $this
     */
    protected function setName(string $name = null)
    {
@@ -531,7 +531,7 @@ class Language extends Model

    /**
     * @param array $slugs
-     * @return self
+     * @return $this
     */
    protected function setSlugs(array $slugs = null)
    {
@@ -541,7 +541,7 @@ class Language extends Model

    /**
     * @param array $smartypants
-     * @return self
+     * @return $this
     */
    protected function setSmartypants(array $smartypants = null)
    {
@@ -551,7 +551,7 @@ class Language extends Model

    /**
     * @param array $translations
-     * @return self
+     * @return $this
     */
    protected function setTranslations(array $translations = null)
    {
@@ -561,7 +561,7 @@ class Language extends Model

    /**
     * @param string $url
-     * @return self
+     * @return $this
     */
    protected function setUrl(string $url = null)
    {
@@ -639,7 +639,7 @@ class Language extends Model
     *
     * @internal
     * @param array $props
-     * @return self
+     * @return static
     */
    public function update(array $props = null)
    {
--- a/kirby/src/Cms/Languages.php
+++ b/kirby/src/Cms/Languages.php
@@ -19,7 +19,7 @@ class Languages extends Collection
    /**
     * Creates a new collection with the given language objects
     *
-     * @param array $objects
+     * @param array $objects `Kirby\Cms\Language` objects
     * @param null $parent
     * @throws \Kirby\Exception\DuplicateException
     */
@@ -76,7 +76,7 @@ class Languages extends Collection
     * Convert all defined languages to a collection
     *
     * @internal
-     * @return self
+     * @return static
     */
    public static function load()
    {
--- a/kirby/src/Cms/Model.php
+++ b/kirby/src/Cms/Model.php
@@ -76,7 +76,7 @@ abstract class Model
     * Setter for the parent Kirby object
     *
     * @param \Kirby\Cms\App|null $kirby
-     * @return self
+     * @return $this
     */
    protected function setKirby(App $kirby = null)
    {
@@ -89,7 +89,7 @@ abstract class Model
     *
     * @internal
     * @param \Kirby\Cms\Site|null $site
-     * @return self
+     * @return $this
     */
    public function setSite(Site $site = null)
    {
--- a/kirby/src/Cms/ModelWithContent.php
+++ b/kirby/src/Cms/ModelWithContent.php
@@ -231,7 +231,7 @@ abstract class ModelWithContent extends Model
     * @param string $field
     * @param int $by
     * @param int $min
-     * @return self
+     * @return static
     */
    public function decrement(string $field, int $by = 1, int $min = 0)
    {
@@ -306,7 +306,7 @@ abstract class ModelWithContent extends Model
     * @param string $field
     * @param int $by
     * @param int|null $max
-     * @return self
+     * @return static
     */
    public function increment(string $field, int $by = 1, int $max = null)
    {
@@ -569,7 +569,7 @@ abstract class ModelWithContent extends Model
     * @param array|null $data
     * @param string|null $languageCode
     * @param bool $overwrite
-     * @return self
+     * @return static
     */
    public function save(array $data = null, string $languageCode = null, bool $overwrite = false)
    {
@@ -585,7 +585,7 @@ abstract class ModelWithContent extends Model
     *
     * @param array|null $data
     * @param bool $overwrite
-     * @return self
+     * @return static
     */
    protected function saveContent(array $data = null, bool $overwrite = false)
    {
@@ -607,7 +607,7 @@ abstract class ModelWithContent extends Model
     * @param array|null $data
     * @param string|null $languageCode
     * @param bool $overwrite
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\InvalidArgumentException If the language for the given code does not exist
     */
    protected function saveTranslation(array $data = null, string $languageCode = null, bool $overwrite = false)
@@ -653,7 +653,7 @@ abstract class ModelWithContent extends Model
     * Sets the Content object
     *
     * @param array|null $content
-     * @return self
+     * @return $this
     */
    protected function setContent(array $content = null)
    {
@@ -669,7 +669,7 @@ abstract class ModelWithContent extends Model
     * Create the translations collection from an array
     *
     * @param array|null $translations
-     * @return self
+     * @return $this
     */
    protected function setTranslations(array $translations = null)
    {
@@ -752,7 +752,7 @@ abstract class ModelWithContent extends Model
     * @param array|null $input
     * @param string|null $languageCode
     * @param bool $validate
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\InvalidArgumentException If the input array contains invalid values
     */
    public function update(array $input = null, string $languageCode = null, bool $validate = false)
--- a/kirby/src/Cms/Page.php
+++ b/kirby/src/Cms/Page.php
@@ -239,7 +239,7 @@ class Page extends ModelWithContent
     * @param string|null $inSection
     * @return array
     */
-    public function blueprints(string $inSection = null): array
+    public function blueprints(?string $inSection = null): array
    {
        if ($inSection !== null) {
            return $this->blueprint()->section($inSection)->blueprints();
@@ -304,7 +304,7 @@ class Page extends ModelWithContent
     * @param string|null $languageCode
     * @return array
     */
-    public function contentFileData(array $data, string $languageCode = null): array
+    public function contentFileData(array $data, ?string $languageCode = null): array
    {
        return A::prepend($data, [
            'title' => $data['title'] ?? null,
@@ -320,7 +320,7 @@ class Page extends ModelWithContent
     * @param string|null $languageCode
     * @return string
     */
-    public function contentFileName(string $languageCode = null): string
+    public function contentFileName(?string $languageCode = null): string
    {
        return $this->intendedTemplate()->name();
    }
@@ -466,7 +466,7 @@ class Page extends ModelWithContent
     *
     * @internal
     * @param mixed $props
-     * @return self
+     * @return static
     */
    public static function factory($props)
    {
@@ -885,7 +885,7 @@ class Page extends ModelWithContent
     * @internal
     * @param string $name
     * @param array $props
-     * @return self
+     * @return static
     */
    public static function model(string $name, array $props = [])
    {
@@ -1175,11 +1175,11 @@ class Page extends ModelWithContent
            $response = $kirby->response()->toArray();

            // cache the result
-            if ($cache !== null) {
+            if ($cache !== null && $kirby->response()->cache() === true) {
                $cache->set($cacheId, [
                    'html'     => $html,
                    'response' => $response
-                ]);
+                ], $kirby->response()->expires() ?? 0);
            }
        }

@@ -1244,7 +1244,7 @@ class Page extends ModelWithContent
     * Sets the Blueprint object
     *
     * @param array|null $blueprint
-     * @return self
+     * @return $this
     */
    protected function setBlueprint(array $blueprint = null)
    {
@@ -1262,7 +1262,7 @@ class Page extends ModelWithContent
     * than computing the dirname afterwards
     *
     * @param string|null $dirname
-     * @return self
+     * @return $this
     */
    protected function setDirname(string $dirname = null)
    {
@@ -1274,7 +1274,7 @@ class Page extends ModelWithContent
     * Sets the draft flag
     *
     * @param bool $isDraft
-     * @return self
+     * @return $this
     */
    protected function setIsDraft(bool $isDraft = null)
    {
@@ -1286,7 +1286,7 @@ class Page extends ModelWithContent
     * Sets the sorting number
     *
     * @param int|null $num
-     * @return self
+     * @return $this
     */
    protected function setNum(int $num = null)
    {
@@ -1298,7 +1298,7 @@ class Page extends ModelWithContent
     * Sets the parent page object
     *
     * @param \Kirby\Cms\Page|null $parent
-     * @return self
+     * @return $this
     */
    protected function setParent(Page $parent = null)
    {
@@ -1310,7 +1310,7 @@ class Page extends ModelWithContent
     * Sets the absolute path to the page
     *
     * @param string|null $root
-     * @return self
+     * @return $this
     */
    protected function setRoot(string $root = null)
    {
@@ -1322,7 +1322,7 @@ class Page extends ModelWithContent
     * Sets the required Page slug
     *
     * @param string $slug
-     * @return self
+     * @return $this
     */
    protected function setSlug(string $slug)
    {
@@ -1334,7 +1334,7 @@ class Page extends ModelWithContent
     * Sets the intended template
     *
     * @param string|null $template
-     * @return self
+     * @return $this
     */
    protected function setTemplate(string $template = null)
    {
@@ -1349,7 +1349,7 @@ class Page extends ModelWithContent
     * Sets the Url
     *
     * @param string|null $url
-     * @return self
+     * @return $this
     */
    protected function setUrl(string $url = null)
    {
--- a/kirby/src/Cms/PageActions.php
+++ b/kirby/src/Cms/PageActions.php
@@ -30,7 +30,7 @@ trait PageActions
     * siblings will not be resorted.
     *
     * @param int|null $num
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException If a draft is being sorted or the directory cannot be moved
     */
    public function changeNum(int $num = null)
@@ -77,7 +77,7 @@ trait PageActions
     *
     * @param string $slug
     * @param string|null $languageCode
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException If the directory cannot be moved
     */
    public function changeSlug(string $slug, string $languageCode = null)
@@ -141,7 +141,7 @@ trait PageActions
     *
     * @param string $slug
     * @param string|null $languageCode
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\NotFoundException If the language for the given language code cannot be found
     * @throws \Kirby\Exception\InvalidArgumentException If the slug for the default language is being changed
     */
@@ -176,7 +176,7 @@ trait PageActions
     *
     * @param string $status "draft", "listed" or "unlisted"
     * @param int|null $position Optional sorting number
-     * @return self
+     * @return static
     * @throws \Kirby\Exception\InvalidArgumentException If an invalid status is being passed
     */
    public function changeStatus(string $status, int $position = null)
@@ -194,7 +194,7 @@ trait PageActions
    }

    /**
-     * @return self
+     * @return static
     */
    protected function changeStatusToDraft()
    {
@@ -208,7 +208,7 @@ trait PageActions

    /**
     * @param int|null $position
-     * @return self
+     * @return $this|static
     */
    protected function changeStatusToListed(int $position = null)
    {
@@ -233,7 +233,7 @@ trait PageActions
    }

    /**
-     * @return self
+     * @return $this|static
     */
    protected function changeStatusToUnlisted()
    {
@@ -257,7 +257,7 @@ trait PageActions
     * status isn't yet `listed`, it will be changed to it.
     *
     * @param int|null $position
-     * @return self
+     * @return $this|static
     */
    public function changeSort(int $position = null)
    {
@@ -268,7 +268,7 @@ trait PageActions
     * Changes the page template
     *
     * @param string $template
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException If the textfile cannot be renamed/moved
     */
    public function changeTemplate(string $template)
@@ -316,7 +316,7 @@ trait PageActions
     *
     * @param string $title
     * @param string|null $languageCode
-     * @return self
+     * @return static
     */
    public function changeTitle(string $title, string $languageCode = null)
    {
@@ -443,7 +443,7 @@ trait PageActions
     * Creates and stores a new page
     *
     * @param array $props
-     * @return self
+     * @return static
     */
    public static function create(array $props)
    {
@@ -498,7 +498,7 @@ trait PageActions
     * Creates a child of the current page
     *
     * @param array $props
-     * @return self
+     * @return static
     */
    public function createChild(array $props)
    {
@@ -655,7 +655,7 @@ trait PageActions
    }

    /**
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException If the folder cannot be moved
     */
    public function publish()
@@ -693,7 +693,7 @@ trait PageActions

    /**
     * Clean internal caches
-     * @return self
+     * @return $this
     */
    public function purge()
    {
@@ -788,9 +788,10 @@ trait PageActions

    /**
     * @deprecated 3.5.0 Use `Page::changeSort()` instead
+     * @todo Remove in 3.6.0
     *
     * @param null $position
-     * @return self
+     * @return $this|static
     */
    public function sort($position = null)
    {
@@ -803,7 +804,7 @@ trait PageActions
     * Convert a page from listed or
     * unlisted to draft.
     *
-     * @return self
+     * @return $this|static
     * @throws \Kirby\Exception\LogicException If the folder cannot be moved
     */
    public function unpublish()
@@ -841,7 +842,7 @@ trait PageActions
     * @param array|null $input
     * @param string|null $languageCode
     * @param bool $validate
-     * @return self
+     * @return static
     */
    public function update(array $input = null, string $languageCode = null, bool $validate = false)
    {
--- a/kirby/src/Cms/PageRules.php
+++ b/kirby/src/Cms/PageRules.php
@@ -254,12 +254,6 @@ class PageRules
     */
    public static function changeTitle(Page $page, string $title): bool
    {
-        if (Str::length($title) === 0) {
-            throw new InvalidArgumentException([
-                'key' => 'page.changeTitle.empty',
-            ]);
-        }
-
        if ($page->permissions()->changeTitle() !== true) {
            throw new PermissionException([
                'key'  => 'page.changeTitle.permission',
@@ -269,6 +263,12 @@ class PageRules
            ]);
        }

+        if (Str::length($title) === 0) {
+            throw new InvalidArgumentException([
+                'key' => 'page.changeTitle.empty',
+            ]);
+        }
+
        return true;
    }

@@ -283,9 +283,12 @@ class PageRules
     */
    public static function create(Page $page): bool
    {
-        if (Str::length($page->slug()) < 1) {
-            throw new InvalidArgumentException([
-                'key' => 'page.slug.invalid',
+        if ($page->permissions()->create() !== true) {
+            throw new PermissionException([
+                'key' => 'page.create.permission',
+                'data' => [
+                    'slug' => $page->slug()
+                ]
            ]);
        }

@@ -300,15 +303,6 @@ class PageRules
            ]);
        }

-        if ($page->permissions()->create() !== true) {
-            throw new PermissionException([
-                'key' => 'page.create.permission',
-                'data' => [
-                    'slug' => $page->slug()
-                ]
-            ]);
-        }
-
        $siblings = $page->parentModel()->children();
        $drafts   = $page->parentModel()->drafts();
        $slug     = $page->slug();
@@ -377,6 +371,8 @@ class PageRules
            ]);
        }

+        self::validateSlugLength($slug);
+
        return true;
    }

@@ -403,19 +399,27 @@ class PageRules
    }

    /**
-     * Ensures that the slug doesn't exceed the maximum length to make
-     * sure that the directory name will be accepted by the filesystem
+     * Ensures that the slug is not empty and doesn't exceed the maximum length
+     * to make sure that the directory name will be accepted by the filesystem
     *
     * @param string $slug New slug to check
     * @return void
-     * @throws \Kirby\Exception\InvalidArgumentException If the slug is too long
+     * @throws \Kirby\Exception\InvalidArgumentException If the slug is empty or too long
     */
    protected static function validateSlugLength(string $slug): void
    {
+        $slugLength = Str::length($slug);
+
+        if ($slugLength === 0) {
+            throw new InvalidArgumentException([
+                'key' => 'page.slug.invalid',
+            ]);
+        }
+
        if ($slugsMaxlength = App::instance()->option('slugs.maxlength', 255)) {
            $maxlength = (int)$slugsMaxlength;

-            if (Str::length($slug) > $maxlength) {
+            if ($slugLength > $maxlength) {
                throw new InvalidArgumentException([
                    'key'  => 'page.slug.maxlength',
                    'data' => [
--- a/kirby/src/Cms/Pages.php
+++ b/kirby/src/Cms/Pages.php
@@ -49,7 +49,7 @@ class Pages extends Collection
     * current collection
     *
     * @param mixed $object
-     * @return self
+     * @return $this
     * @throws \Kirby\Exception\InvalidArgumentException
     */
    public function add($object)
@@ -146,7 +146,7 @@ class Pages extends Collection
     * @param array $pages
     * @param \Kirby\Cms\Model|null $model
     * @param bool $draft
-     * @return self
+     * @return static
     */
    public static function factory(array $pages, Model $model = null, bool $draft = false)
    {
@@ -389,7 +389,7 @@ class Pages extends Collection
     * Include all given items in the collection
     *
     * @param mixed ...$args
-     * @return self
+     * @return $this|static
     */
    public function merge(...$args)
    {
--- a/kirby/src/Cms/Permissions.php
+++ b/kirby/src/Cms/Permissions.php
@@ -153,7 +153,7 @@ class Permissions
     * @param string $category
     * @param string $action
     * @param $setting
-     * @return self
+     * @return $this
     */
    protected function setAction(string $category, string $action, $setting)
    {
@@ -169,7 +169,7 @@ class Permissions

    /**
     * @param bool $setting
-     * @return self
+     * @return $this
     */
    protected function setAll(bool $setting)
    {
@@ -182,7 +182,7 @@ class Permissions

    /**
     * @param array $settings
-     * @return self
+     * @return $this
     */
    protected function setCategories(array $settings)
    {
@@ -204,7 +204,7 @@ class Permissions
    /**
     * @param string $category
     * @param bool $setting
-     * @return self
+     * @return $this
     * @throws \Kirby\Exception\InvalidArgumentException
     */
    protected function setCategory(string $category, bool $setting)
--- a/kirby/src/Cms/Plugin.php
+++ b/kirby/src/Cms/Plugin.php
@@ -135,7 +135,7 @@ class Plugin extends Model

    /**
     * @param string $name
-     * @return self
+     * @return $this
     * @throws \Kirby\Exception\InvalidArgumentException
     */
    protected function setName(string $name)
--- a/kirby/src/Cms/Responder.php
+++ b/kirby/src/Cms/Responder.php
@@ -2,6 +2,7 @@

 namespace Kirby\Cms;

+use Kirby\Exception\InvalidArgumentException;
 use Kirby\Toolkit\Mime;
 use Kirby\Toolkit\Str;

@@ -16,6 +17,14 @@ use Kirby\Toolkit\Str;
 */
 class Responder
 {
+    /**
+     * Timestamp when the response expires
+     * in Kirby's cache
+     *
+     * @var int|null
+     */
+    protected $expires = null;
+
    /**
     * HTTP status code
     *
@@ -30,6 +39,14 @@ class Responder
     */
    protected $body = null;

+    /**
+     * Flag that defines whether the current
+     * response can be cached by Kirby's cache
+     *
+     * @var string
+     */
+    protected $cache = true;
+
    /**
     * HTTP headers
     *
@@ -58,7 +75,7 @@ class Responder
     * Setter and getter for the response body
     *
     * @param string|null $body
-     * @return string|self
+     * @return string|$this
     */
    public function body(string $body = null)
    {
@@ -70,11 +87,77 @@ class Responder
        return $this;
    }

+    /**
+     * Setter and getter for the flag that defines
+     * whether the current response can be cached
+     * by Kirby's cache
+     *
+     * @param bool|null $cache
+     * @return bool|$this
+     */
+    public function cache(?bool $cache = null)
+    {
+        if ($cache === null) {
+            return $this->cache;
+        }
+
+        $this->cache = $cache;
+        return $this;
+    }
+
+    /**
+     * Setter and getter for the cache expiry
+     * timestamp for Kirby's cache
+     *
+     * @param int|string|null $expires Timestamp, number of minutes or time string to parse
+     * @param bool $override If `true`, the already defined timestamp will be overridden
+     * @return int|null|$this
+     */
+    public function expires($expires = null, bool $override = false)
+    {
+        // getter
+        if ($expires === null && $override === false) {
+            return $this->expires;
+        }
+
+        // explicit un-setter
+        if ($expires === null) {
+            $this->expires = null;
+            return $this;
+        }
+
+        // normalize the value to an integer timestamp
+        if (is_int($expires) === true && $expires < 1000000000) {
+            // number of minutes
+            $expires = time() + ($expires * 60);
+        } elseif (is_int($expires) !== true) {
+            // time string
+            $parsedExpires = strtotime($expires);
+
+            if (is_int($parsedExpires) !== true) {
+                throw new InvalidArgumentException('Invalid time string "' . $expires . '"');
+            }
+
+            $expires = $parsedExpires;
+        }
+
+        // by default only ever *reduce* the cache expiry time
+        if (
+            $override === true ||
+            $this->expires === null ||
+            $expires < $this->expires
+        ) {
+            $this->expires = $expires;
+        }
+
+        return $this;
+    }
+
    /**
     * Setter and getter for the status code
     *
     * @param int|null $code
-     * @return int|self
+     * @return int|$this
     */
    public function code(int $code = null)
    {
@@ -94,6 +177,7 @@ class Responder
    public function fromArray(array $response): void
    {
        $this->body($response['body'] ?? null);
+        $this->expires($response['expires'] ?? null);
        $this->code($response['code'] ?? null);
        $this->headers($response['headers'] ?? null);
        $this->type($response['type'] ?? null);
@@ -104,9 +188,10 @@ class Responder
     *
     * @param string $key
     * @param string|false|null $value
-     * @return string|self
+     * @param bool $lazy If `true`, an existing header value is not overridden
+     * @return string|$this
     */
-    public function header(string $key, $value = null)
+    public function header(string $key, $value = null, bool $lazy = false)
    {
        if ($value === null) {
            return $this->headers[$key] ?? null;
@@ -117,6 +202,10 @@ class Responder
            return $this;
        }

+        if ($lazy === true && isset($this->headers[$key]) === true) {
+            return $this;
+        }
+
        $this->headers[$key] = $value;
        return $this;
    }
@@ -125,7 +214,7 @@ class Responder
     * Setter and getter for all headers
     *
     * @param array|null $headers
-     * @return array|self
+     * @return array|$this
     */
    public function headers(array $headers = null)
    {
@@ -141,7 +230,7 @@ class Responder
     * Shortcut to configure a json response
     *
     * @param array|null $json
-     * @return string|self
+     * @return string|$this
     */
    public function json(array $json = null)
    {
@@ -157,7 +246,7 @@ class Responder
     *
     * @param string|null $location
     * @param int|null $code
-     * @return self
+     * @return $this
     */
    public function redirect(?string $location = null, ?int $code = null)
    {
@@ -204,7 +293,7 @@ class Responder
     * Setter and getter for the content type
     *
     * @param string|null $type
-     * @return string|self
+     * @return string|$this
     */
    public function type(string $type = null)
    {
--- a/kirby/src/Cms/Response.php
+++ b/kirby/src/Cms/Response.php
@@ -21,7 +21,7 @@ class Response extends \Kirby\Http\Response
     *
     * @param string $location
     * @param int $code
-     * @return self
+     * @return static
     */
    public static function redirect(string $location = '/', int $code = 302)
    {
--- a/kirby/src/Cms/Role.php
+++ b/kirby/src/Cms/Role.php
@@ -49,7 +49,7 @@ class Role extends Model

    /**
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function admin(array $inject = [])
    {
@@ -92,7 +92,7 @@ class Role extends Model
    /**
     * @param array $props
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function factory(array $props, array $inject = [])
    {
@@ -126,7 +126,7 @@ class Role extends Model
    /**
     * @param string $file
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function load(string $file, array $inject = [])
    {
@@ -146,7 +146,7 @@ class Role extends Model

    /**
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function nobody(array $inject = [])
    {
@@ -166,8 +166,8 @@ class Role extends Model
    }

    /**
-     * @param [type] $description
-     * @return self
+     * @param mixed $description
+     * @return $this
     */
    protected function setDescription($description = null)
    {
@@ -177,7 +177,7 @@ class Role extends Model

    /**
     * @param string $name
-     * @return self
+     * @return $this
     */
    protected function setName(string $name)
    {
@@ -186,8 +186,8 @@ class Role extends Model
    }

    /**
-     * @param [type] $permissions
-     * @return self
+     * @param mixed $permissions
+     * @return $this
     */
    protected function setPermissions($permissions = null)
    {
@@ -196,8 +196,8 @@ class Role extends Model
    }

    /**
-     * @param [type] $title
-     * @return self
+     * @param mixed $title
+     * @return $this
     */
    protected function setTitle($title = null)
    {
--- a/kirby/src/Cms/Roles.php
+++ b/kirby/src/Cms/Roles.php
@@ -23,7 +23,7 @@ class Roles extends Collection
     * roles that can be created by the
     * current user
     *
-     * @return self
+     * @return $this|static
     * @throws \Exception
     */
    public function canBeChanged()
@@ -47,7 +47,7 @@ class Roles extends Collection
     * roles that can be created by the
     * current user
     *
-     * @return self
+     * @return $this|static
     * @throws \Exception
     */
    public function canBeCreated()
@@ -69,7 +69,7 @@ class Roles extends Collection
    /**
     * @param array $roles
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function factory(array $roles, array $inject = [])
    {
@@ -93,7 +93,7 @@ class Roles extends Collection
    /**
     * @param string|null $root
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function load(string $root = null, array $inject = [])
    {
--- a/kirby/src/Cms/Site.php
+++ b/kirby/src/Cms/Site.php
@@ -30,14 +30,14 @@ class Site extends ModelWithContent
    /**
     * The SiteBlueprint object
     *
-     * @var SiteBlueprint
+     * @var \Kirby\Cms\SiteBlueprint
     */
    protected $blueprint;

    /**
     * The error page object
     *
-     * @var Page
+     * @var \Kirby\Cms\Page
     */
    protected $errorPage;

@@ -52,7 +52,7 @@ class Site extends ModelWithContent
    /**
     * The home page object
     *
-     * @var Page
+     * @var \Kirby\Cms\Page
     */
    protected $homePage;

@@ -74,7 +74,7 @@ class Site extends ModelWithContent
    /**
     * The current page object
     *
-     * @var Page
+     * @var \Kirby\Cms\Page
     */
    protected $page;

@@ -142,7 +142,7 @@ class Site extends ModelWithContent

    /**
     * Makes it possible to convert the site model
-     * to a string. Mostly useful for debugging
+     * to a string. Mostly useful for debugging.
     *
     * @return string
     */
@@ -208,7 +208,7 @@ class Site extends ModelWithContent
     * @param string|null $languageCode
     * @return array
     */
-    public function contentFileData(array $data, string $languageCode = null): array
+    public function contentFileData(array $data, ?string $languageCode = null): array
    {
        return A::prepend($data, [
            'title' => $data['title'] ?? null,
@@ -360,11 +360,15 @@ class Site extends ModelWithContent
     *
     * @param string|null $format
     * @param string|null $handler
-     * @return mixed
+     * @return int|string
     */
-    public function modified(string $format = null, string $handler = null)
+    public function modified(?string $format = null, ?string $handler = null)
    {
-        return Dir::modified($this->root(), $format, $handler ?? $this->kirby()->option('date.handler', 'date'));
+        return Dir::modified(
+            $this->root(),
+            $format,
+            $handler ?? $this->kirby()->option('date.handler', 'date')
+        );
    }

    /**
@@ -376,10 +380,11 @@ class Site extends ModelWithContent
     * prop, the home page will be returned if
     * it can be found. (see `Site::homePage()`)
     *
-     * @param string|null $path
+     * @param string|null $path omit for current page,
+     *                          otherwise e.g. `notes/across-the-ocean`
     * @return \Kirby\Cms\Page|null
     */
-    public function page(string $path = null)
+    public function page(?string $path = null)
    {
        if ($path !== null) {
            return $this->find($path);
@@ -496,7 +501,7 @@ class Site extends ModelWithContent
     * @param array $params
     * @return \Kirby\Cms\Pages
     */
-    public function search(string $query = null, $params = [])
+    public function search(?string $query = null, $params = [])
    {
        return $this->index()->search($query, $params);
    }
@@ -505,9 +510,9 @@ class Site extends ModelWithContent
     * Sets the Blueprint object
     *
     * @param array|null $blueprint
-     * @return self
+     * @return $this
     */
-    protected function setBlueprint(array $blueprint = null)
+    protected function setBlueprint(?array $blueprint = null)
    {
        if ($blueprint !== null) {
            $blueprint['model'] = $this;
@@ -524,7 +529,7 @@ class Site extends ModelWithContent
     * else is set.
     *
     * @param string $id
-     * @return self
+     * @return $this
     */
    protected function setErrorPageId(string $id = 'error')
    {
@@ -539,7 +544,7 @@ class Site extends ModelWithContent
     * else is set.
     *
     * @param string $id
-     * @return self
+     * @return $this
     */
    protected function setHomePageId(string $id = 'home')
    {
@@ -552,9 +557,9 @@ class Site extends ModelWithContent
     *
     * @internal
     * @param \Kirby\Cms\Page|null $page
-     * @return self
+     * @return $this
     */
-    public function setPage(Page $page = null)
+    public function setPage(?Page $page = null)
    {
        $this->page = $page;
        return $this;
@@ -564,7 +569,7 @@ class Site extends ModelWithContent
     * Sets the Url
     *
     * @param string|null $url
-     * @return self
+     * @return $this
     */
    protected function setUrl($url = null)
    {
@@ -615,7 +620,7 @@ class Site extends ModelWithContent
     * @param array|null $options
     * @return string
     */
-    public function urlForLanguage(string $languageCode = null, array $options = null): string
+    public function urlForLanguage(?string $languageCode = null, ?array $options = null): string
    {
        if ($language = $this->kirby()->language($languageCode)) {
            return $language->url();
@@ -634,7 +639,7 @@ class Site extends ModelWithContent
     * @param string|null $languageCode
     * @return \Kirby\Cms\Page
     */
-    public function visit($page, string $languageCode = null)
+    public function visit($page, ?string $languageCode = null)
    {
        if ($languageCode !== null) {
            $this->kirby()->setCurrentTranslation($languageCode);
--- a/kirby/src/Cms/SiteActions.php
+++ b/kirby/src/Cms/SiteActions.php
@@ -51,7 +51,7 @@ trait SiteActions
     *
     * @param string $title
     * @param string|null $languageCode
-     * @return self
+     * @return static
     */
    public function changeTitle(string $title, string $languageCode = null)
    {
@@ -82,7 +82,7 @@ trait SiteActions
    /**
     * Clean internal caches
     *
-     * @return self
+     * @return $this
     */
    public function purge()
    {
--- a/kirby/src/Cms/Structure.php
+++ b/kirby/src/Cms/Structure.php
@@ -23,7 +23,7 @@ class Structure extends Collection
    /**
     * Creates a new Collection with the given objects
     *
-     * @param array $objects
+     * @param array $objects Kirby\Cms\StructureObject` objects or props arrays
     * @param object|null $parent
     */
    public function __construct($objects = [], $parent = null)
--- a/kirby/src/Cms/StructureObject.php
+++ b/kirby/src/Cms/StructureObject.php
@@ -35,7 +35,7 @@ class StructureObject extends Model
    protected $id;

    /**
-     * @var Page|Site|File|User
+     * @var \Kirby\Cms\Site|\Kirby\Cms\Page|\Kirby\Cms\File|\Kirby\Cms\User|null
     */
    protected $parent;

@@ -131,7 +131,7 @@ class StructureObject extends Model
     * Sets the Content object with the given parent
     *
     * @param array|null $content
-     * @return self
+     * @return $this
     */
    protected function setContent(array $content = null)
    {
@@ -146,7 +146,7 @@ class StructureObject extends Model
     * specified.
     *
     * @param string $id
-     * @return self
+     * @return $this
     */
    protected function setId(string $id)
    {
@@ -155,11 +155,10 @@ class StructureObject extends Model
    }

    /**
-     * Sets the parent Model. This can either be a
-     * Page, Site, File or User object
+     * Sets the parent Model
     *
-     * @param \Kirby\Cms\Model|null $parent
-     * @return self
+     * @return $this
+     * @param \Kirby\Cms\Site|\Kirby\Cms\Page|\Kirby\Cms\File|\Kirby\Cms\User|null $parent
     */
    protected function setParent(Model $parent = null)
    {
@@ -171,7 +170,7 @@ class StructureObject extends Model
     * Sets the parent Structure collection
     *
     * @param \Kirby\Cms\Structure|null $structure
-     * @return self
+     * @return $this
     */
    protected function setStructure(Structure $structure = null)
    {
--- a/kirby/src/Cms/System.php
+++ b/kirby/src/Cms/System.php
@@ -7,8 +7,6 @@ use Kirby\Exception\Exception;
 use Kirby\Exception\InvalidArgumentException;
 use Kirby\Exception\PermissionException;
 use Kirby\Http\Remote;
-use Kirby\Http\Uri;
-use Kirby\Http\Url;
 use Kirby\Toolkit\A;
 use Kirby\Toolkit\Dir;
 use Kirby\Toolkit\F;
@@ -115,19 +113,7 @@ class System
     */
    public function indexUrl(): string
    {
-        $url = $this->app->url('index');
-
-        if (Url::isAbsolute($url)) {
-            $uri = Url::toObject($url);
-        } else {
-            // index URL was configured without host, use the current host
-            $uri = Uri::current([
-                'path'   => $url,
-                'query'  => null
-            ]);
-        }
-
-        return $uri->setScheme(null)->setSlash(false)->toString();
+        return $this->app->url('index', true)->setScheme(null)->setSlash(false)->toString();
    }

    /**
--- a/kirby/src/Cms/Translation.php
+++ b/kirby/src/Cms/Translation.php
@@ -139,15 +139,17 @@ class Translation
     * @param string $code
     * @param string $root
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function load(string $code, string $root, array $inject = [])
    {
        try {
-            return new Translation($code, array_merge(Data::read($root), $inject));
+            $data = array_merge(Data::read($root), $inject);
        } catch (Exception $e) {
-            return new Translation($code, []);
+            $data = [];
        }
+
+        return new static($code, $data);
    }

    /**
--- a/kirby/src/Cms/Translations.php
+++ b/kirby/src/Cms/Translations.php
@@ -39,7 +39,7 @@ class Translations extends Collection

    /**
     * @param array $translations
-     * @return self
+     * @return static
     */
    public static function factory(array $translations)
    {
@@ -56,7 +56,7 @@ class Translations extends Collection
    /**
     * @param string $root
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function load(string $root, array $inject = [])
    {
--- a/kirby/src/Cms/User.php
+++ b/kirby/src/Cms/User.php
@@ -254,7 +254,7 @@ class User extends ModelWithContent
     *
     * @internal
     * @param mixed $props
-     * @return self
+     * @return static
     */
    public static function factory($props)
    {
@@ -566,7 +566,7 @@ class User extends ModelWithContent
     * Create a dummy nobody
     *
     * @internal
-     * @return self
+     * @return static
     */
    public static function nobody()
    {
@@ -759,7 +759,7 @@ class User extends ModelWithContent
     * Sets the Blueprint object
     *
     * @param array|null $blueprint
-     * @return self
+     * @return $this
     */
    protected function setBlueprint(array $blueprint = null)
    {
@@ -775,7 +775,7 @@ class User extends ModelWithContent
     * Sets the user email
     *
     * @param string $email|null
-     * @return self
+     * @return $this
     */
    protected function setEmail(string $email = null)
    {
@@ -789,7 +789,7 @@ class User extends ModelWithContent
     * Sets the user id
     *
     * @param string $id|null
-     * @return self
+     * @return $this
     */
    protected function setId(string $id = null)
    {
@@ -801,7 +801,7 @@ class User extends ModelWithContent
     * Sets the user language
     *
     * @param string $language|null
-     * @return self
+     * @return $this
     */
    protected function setLanguage(string $language = null)
    {
@@ -813,7 +813,7 @@ class User extends ModelWithContent
     * Sets the user name
     *
     * @param string $name|null
-     * @return self
+     * @return $this
     */
    protected function setName(string $name = null)
    {
@@ -825,7 +825,7 @@ class User extends ModelWithContent
     * Sets the user's password hash
     *
     * @param string $password|null
-     * @return self
+     * @return $this
     */
    protected function setPassword(string $password = null)
    {
@@ -837,7 +837,7 @@ class User extends ModelWithContent
     * Sets the user role
     *
     * @param string $role|null
-     * @return self
+     * @return $this
     */
    protected function setRole(string $role = null)
    {
@@ -942,7 +942,7 @@ class User extends ModelWithContent
        }

        if (password_verify($password, $this->password()) !== true) {
-            throw new InvalidArgumentException(['key' => 'user.password.notSame']);
+            throw new InvalidArgumentException(['key' => 'user.password.wrong']);
        }

        return true;
--- a/kirby/src/Cms/UserActions.php
+++ b/kirby/src/Cms/UserActions.php
@@ -26,7 +26,7 @@ trait UserActions
     * Changes the user email address
     *
     * @param string $email
-     * @return self
+     * @return static
     */
    public function changeEmail(string $email)
    {
@@ -47,7 +47,7 @@ trait UserActions
     * Changes the user language
     *
     * @param string $language
-     * @return self
+     * @return static
     */
    public function changeLanguage(string $language)
    {
@@ -68,7 +68,7 @@ trait UserActions
     * Changes the screen name of the user
     *
     * @param string $name
-     * @return self
+     * @return static
     */
    public function changeName(string $name)
    {
@@ -89,7 +89,7 @@ trait UserActions
     * Changes the user password
     *
     * @param string $password
-     * @return self
+     * @return static
     */
    public function changePassword(string $password)
    {
@@ -108,7 +108,7 @@ trait UserActions
     * Changes the user role
     *
     * @param string $role
-     * @return self
+     * @return static
     */
    public function changeRole(string $role)
    {
@@ -172,7 +172,7 @@ trait UserActions
     * Creates a new User from the given props and returns a new User object
     *
     * @param array|null $props
-     * @return self
+     * @return static
     */
    public static function create(array $props = null)
    {
@@ -304,7 +304,7 @@ trait UserActions
     * @param array|null $input
     * @param string|null $languageCode
     * @param bool $validate
-     * @return self
+     * @return static
     */
    public function update(array $input = null, string $languageCode = null, bool $validate = false)
    {
--- a/kirby/src/Cms/Users.php
+++ b/kirby/src/Cms/Users.php
@@ -38,7 +38,7 @@ class Users extends Collection
     * current collection
     *
     * @param mixed $object
-     * @return self
+     * @return $this
     */
    public function add($object)
    {
@@ -63,7 +63,7 @@ class Users extends Collection
     *
     * @param array $users
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function factory(array $users, array $inject = [])
    {
@@ -98,7 +98,7 @@ class Users extends Collection
     *
     * @param string $root
     * @param array $inject
-     * @return self
+     * @return static
     */
    public static function load(string $root, array $inject = [])
    {
@@ -131,7 +131,7 @@ class Users extends Collection
     * Shortcut for `$users->filter('role', 'admin')`
     *
     * @param string $role
-     * @return self
+     * @return static
     */
    public function role(string $role)
    {