Upgrade to 3.5.5

kirby/src/Api/Api.php

@@ -476,7 +476,7 @@ class Api
      * Setter for the authentication callback
      *
      * @param \Closure|null $authentication
-     * @return self
+     * @return $this
      */
     protected function setAuthentication(Closure $authentication = null)
     {
@@ -488,7 +488,7 @@ class Api
      * Setter for the collections definition
      *
      * @param array|null $collections
-     * @return self
+     * @return $this
      */
     protected function setCollections(array $collections = null)
     {
@@ -502,7 +502,7 @@ class Api
      * Setter for the injected data
      *
      * @param array|null $data
-     * @return self
+     * @return $this
      */
     protected function setData(array $data = null)
     {
@@ -514,7 +514,7 @@ class Api
      * Setter for the debug flag
      *
      * @param bool $debug
-     * @return self
+     * @return $this
      */
     protected function setDebug(bool $debug = false)
     {
@@ -526,7 +526,7 @@ class Api
      * Setter for the model definitions
      *
      * @param array|null $models
-     * @return self
+     * @return $this
      */
     protected function setModels(array $models = null)
     {
@@ -541,7 +541,7 @@ class Api
      * Setter for the request data
      *
      * @param array|null $requestData
-     * @return self
+     * @return $this
      */
     protected function setRequestData(array $requestData = null)
     {
@@ -559,7 +559,7 @@ class Api
      * Setter for the request method
      *
      * @param string|null $requestMethod
-     * @return self
+     * @return $this
      */
     protected function setRequestMethod(string $requestMethod = null)
     {
@@ -571,7 +571,7 @@ class Api
      * Setter for the route definitions
      *
      * @param array|null $routes
-     * @return self
+     * @return $this
      */
     protected function setRoutes(array $routes = null)
     {

kirby/src/Api/Collection.php

@@ -77,7 +77,7 @@ class Collection
 
     /**
      * @param string|array|null $keys
-     * @return self
+     * @return $this
      * @throws \Exception
      */
     public function select($keys = null)
@@ -168,7 +168,7 @@ class Collection
 
     /**
      * @param string $view
-     * @return self
+     * @return $this
      */
     public function view(string $view)
     {

kirby/src/Api/Model.php

@@ -84,7 +84,7 @@ class Model
 
     /**
      * @param null $keys
-     * @return self
+     * @return $this
      * @throws \Exception
      */
     public function select($keys = null)
@@ -225,7 +225,7 @@ class Model
 
     /**
      * @param string $name
-     * @return self
+     * @return $this
      * @throws \Exception
      */
     public function view(string $name)

kirby/src/Cache/FileCache.php

@@ -2,6 +2,7 @@
 
 namespace Kirby\Cache;
 
+use Kirby\Exception\Exception;
 use Kirby\Toolkit\Dir;
 use Kirby\Toolkit\F;
 use Kirby\Toolkit\Str;
@@ -77,19 +78,19 @@ class FileCache extends Cache
                 // forward slashes don't need special treatment
                 case '/':
                     break;
-                
+
                 // backslashes get their own marker in the path
                 // to differentiate the cache key from one with forward slashes
                 case '\\':
                     $keyParts[] = '_backslash';
                     break;
-                
+
                 // empty part means two slashes in a row;
                 // special marker like for backslashes
                 case '':
                     $keyParts[] = '_empty';
                     break;
-                
+
                 // an actual path segment
                 default:
                     // check if the segment only contains safe characters;
@@ -178,10 +179,41 @@ class FileCache extends Cache
     {
         $file = $this->file($key);
 
-        if (is_file($file) === true) {
-            return F::remove($file);
-        } else {
-            return false;
+        if (is_file($file) === true && F::remove($file) === true) {
+            $this->removeEmptyDirectories(dirname($file));
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Removes empty directories safely by checking each directory
+     * up to the root directory
+     *
+     * @param string $dir
+     * @return void
+     */
+    protected function removeEmptyDirectories(string $dir): void
+    {
+        try {
+            // ensure the path doesn't end with a slash for the next comparison
+            $dir = rtrim($dir, '/\/');
+
+            // checks all directory segments until reaching the root directory
+            while (Str::startsWith($dir, $this->root()) === true && $dir !== $this->root()) {
+                $files = array_diff(scandir($dir) ?? [], ['.', '..']);
+
+                if (empty($files) === true && Dir::remove($dir) === true) {
+                    // continue with the next level up
+                    $dir = dirname($dir);
+                } else {
+                    // no need to continue with the next level up as `$dir` was not deleted
+                    break;
+                }
+            }
+        } catch (Exception $e) { // @codeCoverageIgnore
+            // silently stops the process
         }
     }
 

kirby/src/Cache/Value.php

@@ -25,6 +25,8 @@ class Value
 
     /**
      * the number of minutes until the value expires
+     * @todo Rename this property to $expiry to reflect
+     *       both minutes and absolute timestamps
      * @var int
      */
     protected $minutes;
@@ -40,7 +42,8 @@ class Value
      *
      * @param mixed $value
      * @param int $minutes the number of minutes until the value expires
-     * @param int $created the unix timestamp when the value has been created
+     *                     or an absolute UNIX timestamp
+     * @param int $created the UNIX timestamp when the value has been created
      */
     public function __construct($value, int $minutes = 0, int $created = null)
     {
@@ -72,6 +75,11 @@ class Value
             return null;
         }
 
+        if ($this->minutes > 1000000000) {
+            // absolute timestamp
+            return $this->minutes;
+        }
+
         return $this->created + ($this->minutes * 60);
     }
 
@@ -79,7 +87,7 @@ class Value
      * Creates a value object from an array
      *
      * @param array $array
-     * @return self
+     * @return static
      */
     public static function fromArray(array $array)
     {
@@ -91,7 +99,7 @@ class Value
      * returns null on error
      *
      * @param string $json
-     * @return self|null
+     * @return static|null
      */
     public static function fromJson(string $json)
     {

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)
     {

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;
     }
 
     /**

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);
     }
 
     /**

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
      */

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)
     {

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' => [

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)
     {

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
      *

kirby/src/Cms/BlockConverter.php

@@ -219,7 +219,7 @@ class BlockConverter
     {
         return [
             'content' => [
-                'text' => $params['content']
+                'text' => '<p>' . $params['content'] . '</p>'
             ],
             'type' => 'text'
         ];

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)
     {

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 = [])
     {

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)
     {

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)
     {

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)
     {

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)
     {

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()
     {

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)
     {

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()
     {

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)
     {

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 = [])
     {

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)
     {

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)
     {

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)
     {

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)
     {

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()
     {

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)
     {

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)

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)
     {

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)
     {

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' => [

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)
     {

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)

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)

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)
     {

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)
     {

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)
     {

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 = [])
     {

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);

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()
     {

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)

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)
     {

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();
     }
 
     /**

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);
     }
 
     /**

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 = [])
     {

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;

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)
     {

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)
     {

kirby/src/Database/Database.php

@@ -157,7 +157,7 @@ class Database
      * Returns one of the started instances
      *
      * @param string|null $id
-     * @return self|null
+     * @return static|null
      */
     public static function instance(string $id = null)
     {

kirby/src/Database/Query.php

@@ -294,7 +294,7 @@ class Query
      * @param string $table Name of the table, which should be joined
      * @param string $on The on clause for this join
      * @param string $type The join type. Uses an inner join by default
-     * @return self
+     * @return $this
      */
     public function join(string $table, string $on, string $type = 'JOIN')
     {

kirby/src/Email/Body.php

@@ -63,7 +63,7 @@ class Body
      * Sets the HTML content for the email body
      *
      * @param string|null $html
-     * @return self
+     * @return $this
      */
     protected function setHtml(string $html = null)
     {
@@ -75,7 +75,7 @@ class Body
      * Sets the plain text content for the email body
      *
      * @param string|null $text
-     * @return self
+     * @return $this
      */
     protected function setText(string $text = null)
     {

kirby/src/Email/Email.php

@@ -296,7 +296,7 @@ class Email
      * Sets the email attachments
      *
      * @param array|null $attachments
-     * @return self
+     * @return $this
      */
     protected function setAttachments($attachments = null)
     {
@@ -308,7 +308,7 @@ class Email
      * Sets the email body
      *
      * @param string|array $body
-     * @return self
+     * @return $this
      */
     protected function setBody($body)
     {
@@ -336,7 +336,7 @@ class Email
      * Sets the "beforeSend" callback
      *
      * @param \Closure|null $beforeSend
-     * @return self
+     * @return $this
      */
     protected function setBeforeSend(?Closure $beforeSend = null)
     {
@@ -348,7 +348,7 @@ class Email
      * Sets "cc" recipients
      *
      * @param string|array|null $cc
-     * @return self
+     * @return $this
      */
     protected function setCc($cc = null)
     {
@@ -360,7 +360,7 @@ class Email
      * Sets the "from" email address
      *
      * @param string $from
-     * @return self
+     * @return $this
      */
     protected function setFrom(string $from)
     {
@@ -372,7 +372,7 @@ class Email
      * Sets the "from" name
      *
      * @param string|null $fromName
-     * @return self
+     * @return $this
      */
     protected function setFromName(string $fromName = null)
     {
@@ -384,7 +384,7 @@ class Email
      * Sets the "reply to" email address
      *
      * @param string|null $replyTo
-     * @return self
+     * @return $this
      */
     protected function setReplyTo(string $replyTo = null)
     {
@@ -396,7 +396,7 @@ class Email
      * Sets the "reply to" name
      *
      * @param string|null $replyToName
-     * @return self
+     * @return $this
      */
     protected function setReplyToName(string $replyToName = null)
     {
@@ -408,7 +408,7 @@ class Email
      * Sets the email subject
      *
      * @param string $subject
-     * @return self
+     * @return $this
      */
     protected function setSubject(string $subject)
     {
@@ -420,7 +420,7 @@ class Email
      * Sets the recipients of the email
      *
      * @param string|array $to
-     * @return self
+     * @return $this
      */
     protected function setTo($to)
     {
@@ -432,7 +432,7 @@ class Email
      * Sets the email transport settings
      *
      * @param array|null $transport
-     * @return self
+     * @return $this
      */
     protected function setTransport($transport = null)
     {

kirby/src/Form/FieldClass.php

@@ -92,7 +92,7 @@ abstract class FieldClass
     }
 
     /**
-     * DEPRECATED!
+     * @deprecated
      *
      * Returns the field data
      * in a format to be stored
@@ -379,7 +379,7 @@ abstract class FieldClass
     }
 
     /**
-     * DEPRECATED
+     * @deprecated
      *
      * @return bool
      */

kirby/src/Form/Fields.php

@@ -23,7 +23,7 @@ class Fields extends Collection
      *
      * @param string $name
      * @param object|array $field
-     * @return self
+     * @return $this
      */
     public function __set(string $name, $field)
     {

kirby/src/Form/Options.php

@@ -40,7 +40,7 @@ class Options
      * Brings options through api
      *
      * @param $api
-     * @param $model
+     * @param \Kirby\Cms\Model|null $model
      * @return array
      */
     public static function api($api, $model = null): array
@@ -71,7 +71,7 @@ class Options
     }
 
     /**
-     * @param $model
+     * @param \Kirby\Cms\Model $model
      * @return array
      */
     protected static function data($model): array
@@ -100,14 +100,14 @@ class Options
      *
      * @param $options
      * @param array $props
-     * @param null $model
+     * @param \Kirby\Cms\Model|null $model
      * @return array
      */
     public static function factory($options, array $props = [], $model = null): array
     {
         switch ($options) {
             case 'api':
-                $options = static::api($props['api']);
+                $options = static::api($props['api'], $model);
                 break;
             case 'query':
                 $options = static::query($props['query'], $model);
@@ -160,7 +160,7 @@ class Options
      * Brings options with query
      *
      * @param $query
-     * @param null $model
+     * @param \Kirby\Cms\Model|null $model
      * @return array
      */
     public static function query($query, $model = null): array

kirby/src/Form/OptionsApi.php

@@ -149,7 +149,7 @@ class OptionsApi
 
     /**
      * @param array $data
-     * @return self
+     * @return $this
      */
     protected function setData(array $data)
     {
@@ -159,7 +159,7 @@ class OptionsApi
 
     /**
      * @param string|null $fetch
-     * @return self
+     * @return $this
      */
     protected function setFetch(string $fetch = null)
     {
@@ -169,7 +169,7 @@ class OptionsApi
 
     /**
      * @param $options
-     * @return self
+     * @return $this
      */
     protected function setOptions($options = null)
     {
@@ -179,7 +179,7 @@ class OptionsApi
 
     /**
      * @param $text
-     * @return self
+     * @return $this
      */
     protected function setText($text = null)
     {
@@ -189,7 +189,7 @@ class OptionsApi
 
     /**
      * @param $url
-     * @return self
+     * @return $this
      */
     protected function setUrl($url)
     {
@@ -199,7 +199,7 @@ class OptionsApi
 
     /**
      * @param null $value
-     * @return self
+     * @return $this
      */
     protected function setValue($value = null)
     {

kirby/src/Form/OptionsQuery.php

@@ -33,27 +33,27 @@ class OptionsQuery
     protected $aliases = [];
 
     /**
-     * @var
+     * @var array
      */
     protected $data;
 
     /**
-     * @var
+     * @var array|string|null
      */
     protected $options;
 
     /**
-     * @var
+     * @var string
      */
     protected $query;
 
     /**
-     * @var
+     * @var mixed
      */
     protected $text;
 
     /**
-     * @var
+     * @var mixed
      */
     protected $value;
 
@@ -190,9 +190,9 @@ class OptionsQuery
 
     /**
      * @param array|null $aliases
-     * @return self
+     * @return $this
      */
-    protected function setAliases(array $aliases = null)
+    protected function setAliases(?array $aliases = null)
     {
         $this->aliases = $aliases;
         return $this;
@@ -200,7 +200,7 @@ class OptionsQuery
 
     /**
      * @param array $data
-     * @return self
+     * @return $this
      */
     protected function setData(array $data)
     {
@@ -209,8 +209,8 @@ class OptionsQuery
     }
 
     /**
-     * @param $options
-     * @return self
+     * @param array|string|null $options
+     * @return $this
      */
     protected function setOptions($options = null)
     {
@@ -220,7 +220,7 @@ class OptionsQuery
 
     /**
      * @param string $query
-     * @return self
+     * @return $this
      */
     protected function setQuery(string $query)
     {
@@ -229,8 +229,8 @@ class OptionsQuery
     }
 
     /**
-     * @param $text
-     * @return self
+     * @param mixed $text
+     * @return $this
      */
     protected function setText($text)
     {
@@ -239,8 +239,8 @@ class OptionsQuery
     }
 
     /**
-     * @param $value
-     * @return self
+     * @param mixed $value
+     * @return $this
      */
     protected function setValue($value)
     {

kirby/src/Http/Remote.php

@@ -149,7 +149,7 @@ class Remote
     /**
      * Sets up all curl options and sends the request
      *
-     * @return self
+     * @return $this
      */
     public function fetch()
     {
@@ -291,7 +291,7 @@ class Remote
      *
      * @param string $url
      * @param array $params
-     * @return self
+     * @return static
      */
     public static function get(string $url, array $params = [])
     {
@@ -385,7 +385,7 @@ class Remote
      *
      * @param string $url
      * @param array $params
-     * @return self
+     * @return static
      */
     public static function request(string $url, array $params = [])
     {

kirby/src/Http/Response.php

@@ -152,7 +152,7 @@ class Response
      * @param string $file
      * @param string $filename
      * @param array $props Custom overrides for response props (e.g. headers)
-     * @return self
+     * @return static
      */
     public static function download(string $file, string $filename = null, array $props = [])
     {
@@ -188,7 +188,7 @@ class Response
      *
      * @param string $file
      * @param array $props Custom overrides for response props (e.g. headers)
-     * @return self
+     * @return static
      */
     public static function file(string $file, array $props = [])
     {
@@ -229,7 +229,7 @@ class Response
      * @param int $code
      * @param bool $pretty
      * @param array $headers
-     * @return self
+     * @return static
      */
     public static function json($body = '', ?int $code = null, ?bool $pretty = null, array $headers = [])
     {
@@ -252,7 +252,7 @@ class Response
      *
      * @param string $location
      * @param int $code
-     * @return self
+     * @return static
      */
     public static function redirect(string $location = '/', int $code = 302)
     {

kirby/src/Http/Uri.php

@@ -222,7 +222,7 @@ class Uri
      * new props.
      *
      * @param array $props
-     * @return self
+     * @return static
      */
     public function clone(array $props = [])
     {
@@ -238,7 +238,7 @@ class Uri
     /**
      * @param array $props
      * @param bool $forwarded
-     * @return self
+     * @return static
      */
     public static function current(array $props = [], bool $forwarded = false)
     {
@@ -316,7 +316,7 @@ class Uri
      * Tries to convert the internationalized host
      * name to the human-readable UTF8 representation
      *
-     * @return self
+     * @return $this
      */
     public function idn()
     {
@@ -374,7 +374,7 @@ class Uri
 
     /**
      * @param string|null $fragment
-     * @return self
+     * @return $this
      */
     public function setFragment(string $fragment = null)
     {
@@ -384,7 +384,7 @@ class Uri
 
     /**
      * @param string $host
-     * @return self
+     * @return $this
      */
     public function setHost(string $host = null)
     {
@@ -394,7 +394,7 @@ class Uri
 
     /**
      * @param \Kirby\Http\Params|string|array|null $params
-     * @return self
+     * @return $this
      */
     public function setParams($params = null)
     {
@@ -404,7 +404,7 @@ class Uri
 
     /**
      * @param string|null $password
-     * @return self
+     * @return $this
      */
     public function setPassword(string $password = null)
     {
@@ -414,7 +414,7 @@ class Uri
 
     /**
      * @param \Kirby\Http\Path|string|array|null $path
-     * @return self
+     * @return $this
      */
     public function setPath($path = null)
     {
@@ -424,7 +424,7 @@ class Uri
 
     /**
      * @param int|null $port
-     * @return self
+     * @return $this
      */
     public function setPort(int $port = null)
     {
@@ -444,7 +444,7 @@ class Uri
 
     /**
      * @param \Kirby\Http\Query|string|array|null $query
-     * @return self
+     * @return $this
      */
     public function setQuery($query = null)
     {
@@ -454,7 +454,7 @@ class Uri
 
     /**
      * @param string $scheme
-     * @return self
+     * @return $this
      */
     public function setScheme(string $scheme = null)
     {
@@ -471,7 +471,7 @@ class Uri
      * the path when the URI is being built
      *
      * @param bool $slash
-     * @return self
+     * @return $this
      */
     public function setSlash(bool $slash = false)
     {
@@ -481,7 +481,7 @@ class Uri
 
     /**
      * @param string|null $username
-     * @return self
+     * @return $this
      */
     public function setUsername(string $username = null)
     {
@@ -551,7 +551,7 @@ class Uri
      * Tries to convert a URL with an internationalized host
      * name to the machine-readable Punycode representation
      *
-     * @return self
+     * @return $this
      */
     public function unIdn()
     {

kirby/src/Image/Dimensions.php

@@ -67,7 +67,7 @@ class Dimensions
      *
      * @param int $width
      * @param int|null $height
-     * @return self
+     * @return $this
      */
     public function crop(int $width, int $height = null)
     {
@@ -110,7 +110,7 @@ class Dimensions
      * @param int $box the max width and/or height
      * @param bool $force If true, the dimensions will be
      *                    upscaled to fit the box if smaller
-     * @return self object with recalculated dimensions
+     * @return $this object with recalculated dimensions
      */
     public function fit(int $box, bool $force = false)
     {
@@ -162,7 +162,7 @@ class Dimensions
      * @param int|null $fit the max height
      * @param bool $force If true, the dimensions will be
      *                    upscaled to fit the box if smaller
-     * @return self object with recalculated dimensions
+     * @return $this object with recalculated dimensions
      */
     public function fitHeight(int $fit = null, bool $force = false)
     {
@@ -176,7 +176,7 @@ class Dimensions
      * @param int|null $fit the max width
      * @param bool $force If true, the dimensions will be
      *                    upscaled to fit the box if smaller
-     * @return self object with recalculated dimensions
+     * @return $this object with recalculated dimensions
      */
     protected function fitSize(string $ref, int $fit = null, bool $force = false)
     {
@@ -215,7 +215,7 @@ class Dimensions
      * @param int|null $fit the max width
      * @param bool $force If true, the dimensions will be
      *                    upscaled to fit the box if smaller
-     * @return self object with recalculated dimensions
+     * @return $this object with recalculated dimensions
      */
     public function fitWidth(int $fit = null, bool $force = false)
     {
@@ -228,7 +228,7 @@ class Dimensions
      * @param int|null $width the max height
      * @param int|null $height the max width
      * @param bool $force
-     * @return self
+     * @return $this
      */
     public function fitWidthAndHeight(int $width = null, int $height = null, bool $force = false)
     {
@@ -255,7 +255,7 @@ class Dimensions
      * Detect the dimensions for an image file
      *
      * @param string $root
-     * @return self
+     * @return static
      */
     public static function forImage(string $root)
     {
@@ -271,7 +271,7 @@ class Dimensions
      * Detect the dimensions for a svg file
      *
      * @param string $root
-     * @return self
+     * @return static
      */
     public static function forSvg(string $root)
     {
@@ -365,7 +365,7 @@ class Dimensions
      * @param int|null $width
      * @param int|null $height
      * @param bool $force
-     * @return self
+     * @return $this
      */
     public function resize(int $width = null, int $height = null, bool $force = false)
     {
@@ -386,7 +386,7 @@ class Dimensions
      * Resize and crop
      *
      * @param array $options
-     * @return self
+     * @return $this
      */
     public function thumb(array $options = [])
     {

kirby/src/Text/KirbyTag.php

@@ -79,7 +79,7 @@ class KirbyTag
      * @param string $string
      * @param array $data
      * @param array $options
-     * @return self
+     * @return static
      */
     public static function parse(string $string, array $data = [], array $options = [])
     {

kirby/src/Toolkit/Collection.php

@@ -95,7 +95,7 @@ class Collection extends Iterator implements Countable
      *
      * @param string $key string or array
      * @param mixed $value
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function __set(string $key, $value)
     {
@@ -134,7 +134,7 @@ class Collection extends Iterator implements Countable
      * @param mixed $key
      * @param mixed $item
      * @param mixed ...$args
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function append(...$args)
     {
@@ -152,8 +152,8 @@ class Collection extends Iterator implements Countable
      * The last chunk may be smaller
      *
      * @param int $size Number of elements per chunk
-     * @return \Kirby\Toolkit\Collection A new collection with an element for each chunk and
-     *                                   a sub collection in each chunk
+     * @return static A new collection with an element for each chunk and
+     *                a sub collection in each chunk
      */
     public function chunk(int $size)
     {
@@ -183,7 +183,7 @@ class Collection extends Iterator implements Countable
     /**
      * Returns a cloned instance of the collection
      *
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function clone()
     {
@@ -194,7 +194,7 @@ class Collection extends Iterator implements Countable
      * Getter and setter for the data
      *
      * @param array|null $data
-     * @return array|\Kirby\Toolkit\Collection
+     * @return array|$this
      */
     public function data(array $data = null)
     {
@@ -214,7 +214,7 @@ class Collection extends Iterator implements Countable
     /**
      * Clone and remove all elements from the collection
      *
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function empty()
     {
@@ -228,7 +228,7 @@ class Collection extends Iterator implements Countable
      * Adds all elements to the collection
      *
      * @param mixed $items
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function extend($items)
     {
@@ -243,7 +243,7 @@ class Collection extends Iterator implements Countable
      *
      * @param string|array|\Closure $field
      * @param mixed ...$args
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function filter($field, ...$args)
     {
@@ -323,7 +323,7 @@ class Collection extends Iterator implements Countable
      *
      * @param string|Closure $field
      * @param array ...$args
-     * @return self
+     * @return static
      */
     public function filterBy(...$args)
     {
@@ -452,7 +452,7 @@ class Collection extends Iterator implements Countable
     /**
      * Returns the elements in reverse order
      *
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function flip()
     {
@@ -525,7 +525,9 @@ class Collection extends Iterator implements Countable
      *
      * @param string|Closure $field
      * @param bool $i
-     * @return \Kirby\Toolkit\Collection A new collection with an element for each group and a subcollection in each group
+     * @return \Kirby\Toolkit\Collection A new collection with an element for
+     *                                   each group and a subcollection in
+     *                                   each group
      * @throws \Exception if $field is not a string nor a callback function
      */
     public function group($field, bool $i = true)
@@ -586,7 +588,9 @@ class Collection extends Iterator implements Countable
      *
      * @param string|Closure $field
      * @param bool $i
-     * @return \Kirby\Toolkit\Collection A new collection with an element for each group and a sub collection in each group
+     * @return \Kirby\Toolkit\Collection A new collection with an element for
+     *                                   each group and a sub collection in
+     *                                   each group
      * @throws \Exception
      */
     public function groupBy(...$args)
@@ -599,7 +603,7 @@ class Collection extends Iterator implements Countable
      * @since 3.3.0
      *
      * @param \Kirby\Toolkit\Collection $other
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function intersection($other)
     {
@@ -679,7 +683,7 @@ class Collection extends Iterator implements Countable
      * Returns a new object with a limited number of elements
      *
      * @param int $limit The number of elements to return
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function limit(int $limit)
     {
@@ -690,7 +694,7 @@ class Collection extends Iterator implements Countable
      * Map a function to each element
      *
      * @param callable $callback
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function map(callable $callback)
     {
@@ -713,7 +717,7 @@ class Collection extends Iterator implements Countable
      * Returns a Collection without the given element(s)
      *
      * @param string ...$keys any number of keys, passed as individual arguments
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function not(...$keys)
     {
@@ -728,7 +732,7 @@ class Collection extends Iterator implements Countable
      * Returns a new object starting from the given offset
      *
      * @param int $offset The index to start from
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function offset(int $offset)
     {
@@ -739,7 +743,7 @@ class Collection extends Iterator implements Countable
      * Add pagination
      *
      * @param array ...$arguments
-     * @return \Kirby\Toolkit\Collection a sliced set of data
+     * @return static a sliced set of data
      */
     public function paginate(...$arguments)
     {
@@ -795,7 +799,7 @@ class Collection extends Iterator implements Countable
      * @param mixed $key
      * @param mixed $item
      * @param mixed ...$args
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function prepend(...$args)
     {
@@ -817,7 +821,7 @@ class Collection extends Iterator implements Countable
      * Any part of the query is optional.
      *
      * @param array $arguments
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function query(array $arguments = [])
     {
@@ -875,7 +879,7 @@ class Collection extends Iterator implements Countable
      * Removes an element from the array by key
      *
      * @param mixed $key the name of the key
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function remove($key)
     {
@@ -888,7 +892,7 @@ class Collection extends Iterator implements Countable
      *
      * @param mixed $key string or array
      * @param mixed $value
-     * @return \Kirby\Toolkit\Collection
+     * @return $this
      */
     public function set($key, $value = null)
     {
@@ -905,7 +909,7 @@ class Collection extends Iterator implements Countable
     /**
      * Shuffle all elements
      *
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function shuffle()
     {
@@ -928,7 +932,7 @@ class Collection extends Iterator implements Countable
      *
      * @param int $offset The optional index to start the slice from
      * @param int|null $limit The optional number of elements to return
-     * @return \Kirby\Toolkit\Collection
+     * @return $this|static
      */
     public function slice(int $offset = 0, int $limit = null)
     {
@@ -972,7 +976,7 @@ class Collection extends Iterator implements Countable
      * @param string|callable $field Field name or value callback to sort by
      * @param string $direction asc or desc
      * @param int $method The sort flag, SORT_REGULAR, SORT_NUMERIC etc.
-     * @return \Kirby\Toolkit\Collection
+     * @return $this|static
      */
     public function sort()
     {
@@ -1088,7 +1092,7 @@ class Collection extends Iterator implements Countable
      * @param string|callable $field Field name or value callback to sort by
      * @param string $direction asc or desc
      * @param int $method The sort flag, SORT_REGULAR, SORT_NUMERIC etc.
-     * @return Collection
+     * @return $this|static
      */
     public function sortBy(...$args)
     {
@@ -1170,7 +1174,7 @@ class Collection extends Iterator implements Countable
      * Alias for $this->not()
      *
      * @param string ...$keys any number of keys, passed as individual arguments
-     * @return \Kirby\Toolkit\Collection
+     * @return static
      */
     public function without(...$keys)
     {

kirby/src/Toolkit/Dir.php

@@ -69,7 +69,7 @@ class Dir
 
             if (is_dir($root) === true) {
                 if ($recursive === true) {
-                    static::copy($root, $target . '/' . $name);
+                    static::copy($root, $target . '/' . $name, true, $ignore);
                 }
             } else {
                 F::copy($root, $target . '/' . $name);
@@ -254,7 +254,7 @@ class Dir
      * @param string $dir The path of the directory
      * @param string $format
      * @param string $handler
-     * @return int
+     * @return int|string
      */
     public static function modified(string $dir, string $format = null, string $handler = 'date')
     {

kirby/src/Toolkit/Escape.php

@@ -23,6 +23,13 @@ use Laminas\Escaper\Escaper;
  */
 class Escape
 {
+    /**
+     * The internal singleton escaper instance
+     *
+     * @var \Laminas\Escaper\Escaper
+     */
+    protected static $escaper;
+
     /**
      * Escape common HTML attributes data
      *
@@ -43,7 +50,7 @@ class Escape
      */
     public static function attr($string)
     {
-        return (new Escaper('utf-8'))->escapeHtmlAttr($string);
+        return static::escaper()->escapeHtmlAttr($string);
     }
 
     /**
@@ -64,7 +71,17 @@ class Escape
      */
     public static function css($string)
     {
-        return (new Escaper('utf-8'))->escapeCss($string);
+        return static::escaper()->escapeCss($string);
+    }
+
+    /**
+     * Get the escaper instance (and create if needed)
+     *
+     * @return \Laminas\Escaper\Escaper
+     */
+    protected static function escaper()
+    {
+        return static::$escaper = static::$escaper ?? new Escaper('utf-8');
     }
 
     /**
@@ -84,7 +101,7 @@ class Escape
      */
     public static function html($string)
     {
-        return (new Escaper('utf-8'))->escapeHtml($string);
+        return static::escaper()->escapeHtml($string);
     }
 
     /**
@@ -102,7 +119,7 @@ class Escape
      */
     public static function js($string)
     {
-        return (new Escaper('utf-8'))->escapeJs($string);
+        return static::escaper()->escapeJs($string);
     }
 
     /**

kirby/src/Toolkit/F.php

@@ -81,7 +81,6 @@ class F
             'jpeg',
             'jpg',
             'jpe',
-            'jp2',
             'png',
             'ps',
             'psd',

kirby/src/Toolkit/File.php

@@ -59,7 +59,7 @@ class File
      *
      * @param string $target
      * @param bool $force
-     * @return self
+     * @return static
      */
     public function copy(string $target, bool $force = false)
     {
@@ -197,7 +197,7 @@ class File
      *
      * @param string $newRoot
      * @param bool $overwrite Force overwriting any existing files
-     * @return self
+     * @return static
      */
     public function move(string $newRoot, bool $overwrite = false)
     {
@@ -256,7 +256,7 @@ class File
      *
      * @param string $newName
      * @param bool $overwrite Force overwrite existing files
-     * @return self
+     * @return static
      */
     public function rename(string $newName, bool $overwrite = false)
     {

kirby/src/Toolkit/I18n.php

@@ -55,7 +55,9 @@ class I18n
     /**
      * Returns the first fallback locale
      *
-     * @deprecated 3.5.1 Use \Kirby\Toolkit\I18n::fallbacks() instead
+     * @deprecated 3.5.1 Use `\Kirby\Toolkit\I18n::fallbacks()` instead
+     * @todo Add deprecated() helper warning in 3.6.0
+     * @todo Remove in 3.7.0
      *
      * @return string
      */

kirby/src/Toolkit/Pagination.php

@@ -66,7 +66,7 @@ class Pagination
      *
      * @param \Kirby\Toolkit\Collection $collection
      * @param mixed ...$arguments
-     * @return self
+     * @return static
      */
     public static function for(Collection $collection, ...$arguments)
     {
@@ -380,7 +380,7 @@ class Pagination
      * and validates that the properties match
      *
      * @param array $props Array with keys limit, total and/or page
-     * @return self
+     * @return $this
      */
     protected function setProperties(array $props)
     {
@@ -417,7 +417,7 @@ class Pagination
      * Sets the number of items per page
      *
      * @param int $limit
-     * @return self
+     * @return $this
      */
     protected function setLimit(int $limit = 20)
     {
@@ -433,7 +433,7 @@ class Pagination
      * Sets the total number of items
      *
      * @param int $total
-     * @return self
+     * @return $this
      */
     protected function setTotal(int $total = 0)
     {
@@ -450,7 +450,7 @@ class Pagination
      *
      * @param int|string|null $page Int or int in string form;
      *                              automatically determined if null
-     * @return self
+     * @return $this
      */
     protected function setPage($page = null)
     {

kirby/src/Toolkit/Properties.php

@@ -23,7 +23,7 @@ trait Properties
      * initial properties.
      *
      * @param array $props
-     * @return self
+     * @return static
      */
     public function clone(array $props = [])
     {
@@ -34,7 +34,7 @@ trait Properties
      * Creates a clone and fetches all
      * lazy-loaded getters to get a full copy
      *
-     * @return self
+     * @return static
      */
     public function hardcopy()
     {