Upgrade to 3.3.0

kirby/src/Api/Api.php

@@ -8,6 +8,7 @@ use Kirby\Exception\NotFoundException;
 use Kirby\Http\Response;
 use Kirby\Http\Router;
 use Kirby\Toolkit\F;
+use Kirby\Toolkit\Pagination;
 use Kirby\Toolkit\Properties;
 use Kirby\Toolkit\Str;
 use Throwable;
@@ -38,7 +39,7 @@ class Api
     /**
      * Debugging flag
      *
-     * @var boolean
+     * @var bool
      */
     protected $debug = false;
 
@@ -200,8 +201,16 @@ class Api
             }
         }
 
+        // don't throw pagination errors if pagination
+        // page is out of bounds
+        $validate = Pagination::$validate;
+        Pagination::$validate = false;
+
         $output = $this->route->action()->call($this, ...$this->route->arguments());
 
+        // restore old pagination validation mode
+        Pagination::$validate = $validate;
+
         if (is_object($output) === true && is_a($output, 'Kirby\\Http\\Response') !== true) {
             return $this->resolve($output)->toResponse();
         }
@@ -268,7 +277,7 @@ class Api
     /**
      * Returns the debugging flag
      *
-     * @return boolean
+     * @return bool
      */
     public function debug(): bool
     {
@@ -279,7 +288,7 @@ class Api
      * Checks if injected data exists for the given key
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function hasData(string $key): bool
     {
@@ -489,7 +498,7 @@ class Api
     /**
      * Setter for the debug flag
      *
-     * @param boolean $debug
+     * @param bool $debug
      * @return self
      */
     protected function setDebug(bool $debug = false)
@@ -693,7 +702,7 @@ class Api
      * Upload helper method
      *
      * @param Closure $callback
-     * @param boolean $single
+     * @param bool $single
      * @return array
      *
      * @throws Exception If request has no files

kirby/src/Cache/ApcuCache.php

@@ -2,7 +2,7 @@
 
 namespace Kirby\Cache;
 
-use APCUIterator;
+use APCuIterator;
 
 /**
  * APCu Cache Driver
@@ -19,7 +19,7 @@ class ApcuCache extends Cache
      * Determines if an item exists in the cache
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function exists(string $key): bool
     {
@@ -30,12 +30,12 @@ class ApcuCache extends Cache
      * Flushes the entire cache and returns
      * whether the operation was successful
      *
-     * @return boolean
+     * @return bool
      */
     public function flush(): bool
     {
         if (empty($this->options['prefix']) === false) {
-            return apcu_delete(new APCUIterator('!^' . preg_quote($this->options['prefix']) . '!'));
+            return apcu_delete(new APCuIterator('!^' . preg_quote($this->options['prefix']) . '!'));
         } else {
             return apcu_clear_cache();
         }
@@ -46,7 +46,7 @@ class ApcuCache extends Cache
      * whether the operation was successful
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function remove(string $key): bool
     {
@@ -77,7 +77,7 @@ class ApcuCache extends Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     public function set(string $key, $value, int $minutes = 0): bool
     {

kirby/src/Cache/Cache.php

@@ -45,14 +45,14 @@ abstract class Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     abstract public function set(string $key, $value, int $minutes = 0): bool;
 
     /**
      * Adds the prefix to the key if given
      *
-     * @param  string $key
+     * @param string $key
      * @return string
      */
     protected function key(string $key): string
@@ -152,7 +152,7 @@ abstract class Cache
      * Checks if an item in the cache is expired
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function expired(string $key): bool
     {
@@ -204,7 +204,7 @@ abstract class Cache
      * Determines if an item exists in the cache
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function exists(string $key): bool
     {
@@ -217,7 +217,7 @@ abstract class Cache
      * this needs to be defined by the driver
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     abstract public function remove(string $key): bool;
 
@@ -226,7 +226,7 @@ abstract class Cache
      * whether the operation was successful;
      * this needs to be defined by the driver
      *
-     * @return boolean
+     * @return bool
      */
     abstract public function flush(): bool;
 

kirby/src/Cache/FileCache.php

@@ -78,7 +78,7 @@ class FileCache extends Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     public function set(string $key, $value, int $minutes = 0): bool
     {
@@ -125,7 +125,7 @@ class FileCache extends Cache
      * whether the operation was successful
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function remove(string $key): bool
     {
@@ -142,7 +142,7 @@ class FileCache extends Cache
      * Flushes the entire cache and returns
      * whether the operation was successful
      *
-     * @return boolean
+     * @return bool
      */
     public function flush(): bool
     {

kirby/src/Cache/MemCached.php

@@ -52,7 +52,7 @@ class MemCached extends Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     public function set(string $key, $value, int $minutes = 0): bool
     {
@@ -76,7 +76,7 @@ class MemCached extends Cache
      * whether the operation was successful
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function remove(string $key): bool
     {
@@ -88,7 +88,7 @@ class MemCached extends Cache
      * whether the operation was successful;
      * WARNING: Memcached only supports flushing the whole cache at once!
      *
-     * @return boolean
+     * @return bool
      */
     public function flush(): bool
     {

kirby/src/Cache/MemoryCache.php

@@ -31,7 +31,7 @@ class MemoryCache extends Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     public function set(string $key, $value, int $minutes = 0): bool
     {
@@ -56,7 +56,7 @@ class MemoryCache extends Cache
      * whether the operation was successful
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function remove(string $key): bool
     {
@@ -72,7 +72,7 @@ class MemoryCache extends Cache
      * Flushes the entire cache and returns
      * whether the operation was successful
      *
-     * @return boolean
+     * @return bool
      */
     public function flush(): bool
     {

kirby/src/Cache/NullCache.php

@@ -25,7 +25,7 @@ class NullCache extends Cache
      * @param string $key
      * @param mixed $value
      * @param int $minutes
-     * @return boolean
+     * @return bool
      */
     public function set(string $key, $value, int $minutes = 0): bool
     {
@@ -49,7 +49,7 @@ class NullCache extends Cache
      * whether the operation was successful
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function remove(string $key): bool
     {
@@ -60,7 +60,7 @@ class NullCache extends Cache
      * Flushes the entire cache and returns
      * whether the operation was successful
      *
-     * @return boolean
+     * @return bool
      */
     public function flush(): bool
     {

kirby/src/Cms/Api.php

@@ -37,9 +37,7 @@ class Api extends BaseApi
         $this->setRequestMethod($method);
         $this->setRequestData($requestData);
 
-        if ($languageCode = $this->language()) {
-            $this->kirby->setCurrentLanguage($languageCode);
-        }
+        $this->kirby->setCurrentLanguage($this->language());
 
         if ($user = $this->kirby->user()) {
             $this->kirby->setCurrentTranslation($user->language());

kirby/src/Cms/App.php

@@ -4,6 +4,7 @@ namespace Kirby\Cms;
 
 use Kirby\Data\Data;
 use Kirby\Email\PHPMailer as Emailer;
+use Kirby\Exception\ErrorPageException;
 use Kirby\Exception\InvalidArgumentException;
 use Kirby\Exception\NotFoundException;
 use Kirby\Http\Request;
@@ -56,6 +57,7 @@ class App
     protected $languages;
     protected $locks;
     protected $multilang;
+    protected $nonce;
     protected $options;
     protected $path;
     protected $request;
@@ -120,9 +122,15 @@ class App
         $this->extensionsFromOptions();
         $this->extensionsFromFolders();
 
+        // trigger hook for use in plugins
+        $this->trigger('system.loadPlugins:after');
+
         // handle those damn errors
         $this->handleErrors();
 
+        // execute a ready callback from the config
+        $this->optionsFromReadyCallback();
+
         // bake config
         Config::$data = $this->options;
     }
@@ -475,7 +483,7 @@ class App
      *
      * @param string $path
      * @param mixed $parent
-     * @param boolean $drafts
+     * @param bool $drafts
      * @return \Kirby\Cms\File|null
      */
     public function file(string $path, $parent = null, bool $drafts = true)
@@ -586,7 +594,11 @@ class App
 
         // Pages
         if (is_a($input, 'Kirby\Cms\Page')) {
-            $html = $input->render();
+            try {
+                $html = $input->render();
+            } catch (ErrorPageException $e) {
+                return $this->io($e);
+            }
 
             if ($input->isErrorPage() === true) {
                 if ($response->code() === null) {
@@ -758,7 +770,7 @@ class App
     /**
      * Check for a multilang setup
      *
-     * @return boolean
+     * @return bool
      */
     public function multilang(): bool
     {
@@ -769,6 +781,17 @@ class App
         return $this->multilang = $this->languages()->count() !== 0;
     }
 
+    /**
+     * Returns the nonce, which is used
+     * in the panel for inline scripts
+     *
+     * @return string
+     */
+    public function nonce(): string
+    {
+        return $this->nonce = $this->nonce ?? base64_encode(random_bytes(20));
+    }
+
     /**
      * Load a specific configuration option
      *
@@ -791,17 +814,6 @@ class App
         return $this->options;
     }
 
-    /**
-     * Inject options from Kirby instance props
-     *
-     * @param array $options
-     * @return array
-     */
-    protected function optionsFromProps(array $options = []): array
-    {
-        return $this->options = array_replace_recursive($this->options, $options);
-    }
-
     /**
      * Load all options from files in site/config
      *
@@ -823,16 +835,49 @@ class App
         return $this->options = array_replace_recursive($config, $main, $host, $addr);
     }
 
+    /**
+     * Inject options from Kirby instance props
+     *
+     * @param array $options
+     * @return array
+     */
+    protected function optionsFromProps(array $options = []): array
+    {
+        return $this->options = array_replace_recursive($this->options, $options);
+    }
+
+    /**
+     * Merge last-minute options from ready callback
+     *
+     * @return array
+     */
+    protected function optionsFromReadyCallback(): array
+    {
+        if (isset($this->options['ready']) === true && is_callable($this->options['ready']) === true) {
+            // fetch last-minute options from the callback
+            $options = (array)$this->options['ready']($this);
+
+            // inject all last-minute options recursively
+            $this->options = array_replace_recursive($this->options, $options);
+        }
+
+        return $this->options;
+    }
+
     /**
      * Returns any page from the content folder
      *
-     * @param string $id
+     * @param string $id|null
      * @param \Kirby\Cms\Page|\Kirby\Cms\Site|null $parent
      * @param bool $drafts
      * @return \Kirby\Cms\Page|null
      */
-    public function page(string $id, $parent = null, bool $drafts = true)
+    public function page(?string $id = null, $parent = null, bool $drafts = true)
     {
+        if ($id === null) {
+            return null;
+        }
+
         $parent = $parent ?? $this->site();
 
         if ($page = $parent->find($id)) {
@@ -1184,10 +1229,20 @@ class App
     {
         $options = $this->option('smartypants', []);
 
-        if ($options === true) {
+        if ($options === false) {
+            return $text;
+        } elseif (is_array($options) === false) {
             $options = [];
         }
 
+        if ($this->multilang() === true) {
+            $languageSmartypants = $this->language()->smartypants() ?? [];
+
+            if (empty($languageSmartypants) === false) {
+                $options = array_merge($options, $languageSmartypants);
+            }
+        }
+
         return $this->component('smartypants')($this, $text, $options);
     }
 

kirby/src/Cms/AppErrors.php

@@ -29,18 +29,17 @@ trait AppErrors
 
     protected function handleErrors()
     {
-        $request = $this->request();
-
-        // TODO: implement acceptance
-        if ($request->ajax()) {
-            return $this->handleJsonErrors();
+        if ($this->request()->cli() === true) {
+            $this->handleCliErrors();
+            return;
         }
 
-        if ($request->cli()) {
-            return $this->handleCliErrors();
+        if ($this->visitor()->prefersJson() === true) {
+            $this->handleJsonErrors();
+            return;
         }
 
-        return $this->handleHtmlErrors();
+        $this->handleHtmlErrors();
     }
 
     protected function handleHtmlErrors()

kirby/src/Cms/AppPlugins.php

@@ -701,7 +701,6 @@ trait AppPlugins
     protected function pluginsLoader(): array
     {
         $root   = $this->root('plugins');
-        $kirby  = $this;
         $loaded = [];
 
         foreach (Dir::read($root) as $dirname) {
@@ -709,14 +708,10 @@ trait AppPlugins
                 continue;
             }
 
-            if (is_dir($root . '/' . $dirname) === false) {
-                continue;
-            }
-
             $dir   = $root . '/' . $dirname;
             $entry = $dir . '/index.php';
 
-            if (file_exists($entry) === false) {
+            if (is_dir($dir) !== true || is_file($entry) !== true) {
                 continue;
             }
 

kirby/src/Cms/AppTranslations.php

@@ -158,7 +158,7 @@ trait AppTranslations
         $inject = $this->extensions['translations'][$locale] ?? [];
 
         // load from disk instead
-        return Translation::load($locale, $this->root('translations') . '/' . $locale . '.json', $inject);
+        return Translation::load($locale, $this->root('i18n:translations') . '/' . $locale . '.json', $inject);
     }
 
     /**
@@ -172,6 +172,6 @@ trait AppTranslations
             return $this->translations;
         }
 
-        return Translations::load($this->root('translations'), $this->extensions['translations'] ?? []);
+        return Translations::load($this->root('i18n:translations'), $this->extensions['translations'] ?? []);
     }
 }

kirby/src/Cms/AppUsers.php

@@ -77,7 +77,7 @@ trait AppUsers
      * Returns a specific user by id
      * or the current user if no id is given
      *
-     * @param  string $id
+     * @param string $id
      * @return \Kirby\Cms\User|null
      */
     public function user(string $id = null)

kirby/src/Cms/Auth.php

@@ -165,7 +165,7 @@ class Auth
      * Check if logins are blocked for the current ip or email
      *
      * @param string $email
-     * @return boolean
+     * @return bool
      */
     public function isBlocked(string $email): bool
     {
@@ -195,7 +195,7 @@ class Auth
      *
      * @param string $email
      * @param string $password
-     * @param boolean $long
+     * @param bool $long
      * @return \Kirby\Cms\User
      *
      * @throws PermissionException If the rate limit was exceeded or if any other error occured with debug mode off
@@ -243,7 +243,7 @@ class Auth
                 $message = 'Invalid email or password';
             }
 
-            throw new PermissionException($message, 403);
+            throw new PermissionException($message);
         }
 
         // validate the user
@@ -334,7 +334,7 @@ class Auth
     /**
      * Logout the current user
      *
-     * @return boolean
+     * @return bool
      */
     public function logout(): bool
     {
@@ -354,7 +354,7 @@ class Auth
      * Tracks a login
      *
      * @param string $email
-     * @return boolean
+     * @return bool
      */
     public function track(string $email): bool
     {

kirby/src/Cms/Blueprint.php

@@ -472,7 +472,7 @@ class Blueprint
         return [
             'label' => 'Error',
             'name'  => $name,
-            'text'  => $message,
+            'text'  => strip_tags($message),
             'theme' => 'negative',
             'type'  => 'info',
         ];
@@ -595,12 +595,17 @@ class Blueprint
                 continue;
             }
 
+            // fallback to default props when true is passed
+            if ($sectionProps === true) {
+                $sectionProps = [];
+            }
+
             // inject all section extensions
             $sectionProps = $this->extend($sectionProps);
 
             $sections[$sectionName] = $sectionProps = array_merge($sectionProps, [
                 'name' => $sectionName,
-                'type' => $type = $sectionProps['type'] ?? null
+                'type' => $type = $sectionProps['type'] ?? $sectionName
             ]);
 
             if (empty($type) === true || is_string($type) === false) {

kirby/src/Cms/Collection.php

@@ -38,8 +38,8 @@ class Collection extends BaseCollection
     /**
      * Magic getter function
      *
-     * @param  string $key
-     * @param  mixed  $arguments
+     * @param string $key
+     * @param mixed $arguments
      * @return mixed
      */
     public function __call(string $key, $arguments)
@@ -101,8 +101,8 @@ class Collection extends BaseCollection
     /**
      * Appends an element to the data array
      *
-     * @param  mixed $key Optional collection key, will be determined from the item if not given
-     * @param  mixed $item
+     * @param mixed $key Optional collection key, will be determined from the item if not given
+     * @param mixed $item
      * @return \Kirby\Cms\Collection
      */
     public function append(...$args)
@@ -165,7 +165,7 @@ class Collection extends BaseCollection
      * is in the collection
      *
      * @param string|object $id
-     * @return boolean
+     * @return bool
      */
     public function has($id): bool
     {
@@ -181,7 +181,7 @@ class Collection extends BaseCollection
      * The method will automatically detect objects
      * or ids and then search accordingly.
      *
-     * @param  string|object $object
+     * @param string|object $object
      * @return int
      */
     public function indexOf($object): int
@@ -196,7 +196,7 @@ class Collection extends BaseCollection
     /**
      * Returns a Collection without the given element(s)
      *
-     * @param  mixed ...$keys any number of keys, passed as individual arguments
+     * @param mixed ...$keys any number of keys, passed as individual arguments
      * @return \Kirby\Cms\Collection
      */
     public function not(...$keys)
@@ -216,7 +216,7 @@ class Collection extends BaseCollection
     /**
      * Add pagination and return a sliced set of data.
      *
-     * @param  mixed ...$arguments
+     * @param mixed ...$arguments
      * @return \Kirby\Cms\Collection
      */
     public function paginate(...$arguments)
@@ -240,9 +240,9 @@ class Collection extends BaseCollection
     /**
      * Prepends an element to the data array
      *
-     * @param  mixed $key Optional collection key, will be determined from the item if not given
-     * @param  mixed $item
-     * @return Kirby\Cms\Collection
+     * @param mixed $key Optional collection key, will be determined from the item if not given
+     * @param mixed $item
+     * @return \Kirby\Cms\Collection
      */
     public function prepend(...$args)
     {
@@ -321,7 +321,7 @@ class Collection extends BaseCollection
      * to an array. This can also take a callback
      * function to further modify the array result.
      *
-     * @param  Closure $map
+     * @param Closure $map
      * @return array
      */
     public function toArray(Closure $map = null): array

kirby/src/Cms/Collections.php

@@ -42,8 +42,8 @@ class Collections
      * Magic caller to enable something like
      * `$collections->myCollection()`
      *
-     * @param  string $name
-     * @param  array $arguments
+     * @param string $name
+     * @param array $arguments
      * @return \Kirby\Cms\Collection|null
      */
     public function __call(string $name, array $arguments = [])
@@ -89,7 +89,7 @@ class Collections
      * Checks if a collection exists
      *
      * @param string $name
-     * @return boolean
+     * @return bool
      */
     public function has(string $name): bool
     {
@@ -109,7 +109,7 @@ class Collections
      * Loads collection from php file in a
      * given directory or from plugin extension.
      *
-     * @param  string $name
+     * @param string $name
      * @return mixed
      */
     public function load(string $name)

kirby/src/Cms/Content.php

@@ -69,7 +69,7 @@ class Content
      * Same as `self::data()` to improve
      * `var_dump` output
      *
-     * @see    self::data()
+     * @see self::data()
      * @return array
      */
     public function __debugInfo(): array
@@ -146,7 +146,7 @@ class Content
      * Returns either a single field object
      * or all registered fields
      *
-     * @param  string $key
+     * @param string $key
      * @return \Kirby\Cms\Field|array
      */
     public function get(string $key = null)
@@ -172,7 +172,7 @@ class Content
      * Checks if a content field is set
      *
      * @param string $key
-     * @return boolean
+     * @return bool
      */
     public function has(string $key): bool
     {
@@ -197,7 +197,7 @@ class Content
      * without the fields, specified by the
      * passed key(s)
      *
-     * @param  string ...$keys
+     * @param string ...$keys
      * @return self
      */
     public function not(...$keys)
@@ -238,8 +238,8 @@ class Content
     /**
      * Returns the raw data array
      *
-     * @see     self::data()
-     * @return  array
+     * @see self::data()
+     * @return array
      */
     public function toArray(): array
     {
@@ -250,8 +250,8 @@ class Content
      * Updates the content and returns
      * a cloned object
      *
-     * @param  array $content
-     * @param  bool $overwrite
+     * @param array $content
+     * @param bool $overwrite
      * @return self
      */
     public function update(array $content = null, bool $overwrite = false)

kirby/src/Cms/ContentLock.php

@@ -85,7 +85,7 @@ class ContentLock
                 'user'       => $user->id(),
                 'email'      => $user->email(),
                 'time'       => $time,
-                'unlockable' => ($time + 200) <= time()
+                'unlockable' => ($time + 60) <= time()
             ];
         }
 
@@ -144,7 +144,10 @@ class ContentLock
 
         // check if lock was set by another user
         if ($this->data['lock']['user'] !== $this->user()->id()) {
-            throw new LogicException('The content lock can only be removed by the user who created it. Use unlock instead.', 409);
+            throw new LogicException([
+                'fallback' => 'The content lock can only be removed by the user who created it. Use unlock instead.',
+                'httpCode' => 409
+            ]);
         }
 
         // remove lock

kirby/src/Cms/ContentLocks.php

@@ -121,7 +121,7 @@ class ContentLocks
      * Returns the file handle to a `.lock` file
      *
      * @param string $file
-     * @param boolean $create Whether to create the file if it does not exist
+     * @param bool $create Whether to create the file if it does not exist
      * @return resource|null File handle
      */
     protected function handle(string $file, bool $create = false)
@@ -167,7 +167,7 @@ class ContentLocks
      *
      * @param \Kirby\Cms\ModelWithContent $model
      * @param array $data
-     * @return boolean
+     * @return bool
      */
     public function set(ModelWithContent $model, array $data): bool
     {

kirby/src/Cms/ContentTranslation.php

@@ -119,7 +119,7 @@ class ContentTranslation
     /**
      * Checks if the translation file exists
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -140,7 +140,7 @@ class ContentTranslation
      * Checks if the this is the default translation
      * of the model
      *
-     * @return boolean
+     * @return bool
      */
     public function isDefault(): bool
     {

kirby/src/Cms/Dir.php

@@ -27,7 +27,7 @@ class Dir extends \Kirby\Toolkit\Dir
      * @param string $dir
      * @param string $contentExtension
      * @param array $contentIgnore
-     * @param boolean $multilang
+     * @param bool $multilang
      * @return array
      */
     public static function inventory(string $dir, string $contentExtension = 'txt', array $contentIgnore = null, bool $multilang = false): array

kirby/src/Cms/Field.php

@@ -95,7 +95,7 @@ class Field
      *
      * @param object $parent
      * @param string $key
-     * @param mixed  $value
+     * @param mixed $value
      */
     public function __construct($parent = null, string $key, $value)
     {
@@ -130,7 +130,7 @@ class Field
     /**
      * Checks if the field exists in the content data array
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -140,7 +140,7 @@ class Field
     /**
      * Checks if the field content is empty
      *
-     * @return boolean
+     * @return bool
      */
     public function isEmpty(): bool
     {
@@ -150,7 +150,7 @@ class Field
     /**
      * Checks if the field content is not empty
      *
-     * @return boolean
+     * @return bool
      */
     public function isNotEmpty(): bool
     {
@@ -232,7 +232,7 @@ class Field
      * the modified field will be returned. Otherwise it
      * will return the field value.
      *
-     * @param  string|Closure  $value
+     * @param string|Closure $value
      * @return mixed
      */
     public function value($value = null)

kirby/src/Cms/File.php

@@ -231,12 +231,14 @@ class File extends ModelWithContent
      * gets dragged onto a textarea
      *
      * @internal
-     * @param string $type (auto|kirbytext|markdown)
+     * @param string $type (null|auto|kirbytext|markdown)
      * @param bool $absolute
      * @return string
      */
-    public function dragText($type = 'auto', bool $absolute = false): string
+    public function dragText(string $type = null, bool $absolute = false): string
     {
+        $type = $type ?? 'auto';
+
         if ($type === 'auto') {
             $type = option('panel.kirbytext', true) ? 'kirbytext' : 'markdown';
         }
@@ -363,14 +365,16 @@ class File extends ModelWithContent
      */
     public function meta()
     {
+        deprecated('$file->meta() is deprecated, use $file->content() instead. $file->meta() will be removed in Kirby 3.5.0.');
+
         return $this->content();
     }
 
     /**
      * Get the file's last modification time.
      *
-     * @param  string $format
-     * @param  string|null $handler date or strftime
+     * @param string $format
+     * @param string|null $handler date or strftime
      * @return mixed
      */
     public function modified(string $format = null, string $handler = null)
@@ -392,7 +396,7 @@ class File extends ModelWithContent
      * Timestamp of the last modification
      * of the content file
      *
-     * @return integer
+     * @return int
      */
     protected function modifiedContent(): int
     {
@@ -403,7 +407,7 @@ class File extends ModelWithContent
      * Timestamp of the last modification
      * of the source file
      *
-     * @return integer
+     * @return int
      */
     protected function modifiedFile(): int
     {

kirby/src/Cms/FileActions.php

@@ -82,7 +82,7 @@ trait FileActions
     /**
      * Changes the file's sorting number in the meta file
      *
-     * @param integer $sort
+     * @param int $sort
      * @return self
      */
     public function changeSort(int $sort)
@@ -256,6 +256,8 @@ trait FileActions
      */
     public function rename(string $name, bool $sanitize = true)
     {
+        deprecated('$file->rename() is deprecated, use $file->changeName() instead. $file->rename() will be removed in Kirby 3.5.0.');
+
         return $this->changeName($name, $sanitize);
     }
 

kirby/src/Cms/FileBlueprint.php

@@ -44,7 +44,7 @@ class FileBlueprint extends Blueprint
     }
 
     /**
-     * @param  mixed $accept
+     * @param mixed $accept
      * @return array
      */
     protected function normalizeAccept($accept = null): array

kirby/src/Cms/FileFoundation.php

@@ -82,7 +82,7 @@ trait FileFoundation
     /**
      * Checks if the file exists on disk
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -102,7 +102,7 @@ trait FileFoundation
     /**
      * Converts the file to html
      *
-     * @param  array  $attr
+     * @param array $attr
      * @return string
      */
     public function html(array $attr = []): string
@@ -117,7 +117,7 @@ trait FileFoundation
     /**
      * Checks if the file is a resizable image
      *
-     * @return boolean
+     * @return bool
      */
     public function isResizable(): bool
     {
@@ -136,7 +136,7 @@ trait FileFoundation
      * Checks if a preview can be displayed for the file
      * in the panel or in the frontend
      *
-     * @return boolean
+     * @return bool
      */
     public function isViewable(): bool
     {
@@ -165,8 +165,8 @@ trait FileFoundation
     /**
      * Get the file's last modification time.
      *
-     * @param  string $format
-     * @param  string|null $handler date or strftime
+     * @param string $format
+     * @param string|null $handler date or strftime
      * @return mixed
      */
     public function modified(string $format = null, string $handler = null)

kirby/src/Cms/FileModifications.php

@@ -18,7 +18,7 @@ trait FileModifications
     /**
      * Blurs the image by the given amount of pixels
      *
-     * @param boolean $pixels
+     * @param bool $pixels
      * @return \Kirby\Cms\FileVersion|\Kirby\Cms\File
      */
     public function blur($pixels = true)
@@ -39,8 +39,8 @@ trait FileModifications
     /**
      * Crops the image by the given width and height
      *
-     * @param integer $width
-     * @param integer $height
+     * @param int $width
+     * @param int $height
      * @param string|array $options
      * @return \Kirby\Cms\FileVersion|\Kirby\Cms\File
      */
@@ -71,7 +71,7 @@ trait FileModifications
     /**
      * Sets the JPEG compression quality
      *
-     * @param integer $quality
+     * @param int $quality
      * @return \Kirby\Cms\FileVersion|\Kirby\Cms\File
      */
     public function quality(int $quality)
@@ -83,9 +83,9 @@ trait FileModifications
      * Resizes the file with the given width and height
      * while keeping the aspect ratio.
      *
-     * @param integer $width
-     * @param integer $height
-     * @param integer $quality
+     * @param int $width
+     * @param int $height
+     * @param int $quality
      * @return \Kirby\Cms\FileVersion|\Kirby\Cms\File
      */
     public function resize(int $width = null, int $height = null, int $quality = null)

kirby/src/Cms/FilePicker.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Kirby\Cms;
+
+use Kirby\Exception\InvalidArgumentException;
+
+/**
+ * The FilePicker class helps to
+ * fetch the right files for the API calls
+ * for the file picker component in the panel.
+ *
+ * @package   Kirby Cms
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://getkirby.com/license
+ */
+class FilePicker extends Picker
+{
+    /**
+     * Extends the basic defaults
+     *
+     * @return array
+     */
+    public function defaults(): array
+    {
+        $defaults = parent::defaults();
+        $defaults['text'] = '{{ file.filename }}';
+
+        return $defaults;
+    }
+
+    /**
+     * Search all files for the picker
+     *
+     * @return \Kirby\Cms\Files|null
+     */
+    public function items()
+    {
+        $model = $this->options['model'];
+
+        // find the right default query
+        if (empty($this->options['query']) === false) {
+            $query = $this->options['query'];
+        } elseif (is_a($model, 'Kirby\Cms\File') === true) {
+            $query = 'file.siblings';
+        } else {
+            $query = $model::CLASS_ALIAS . '.files';
+        }
+
+        // fetch all files for the picker
+        $files = $model->query($query);
+
+        // help mitigate some typical query usage issues
+        // by converting site and page objects to proper
+        // pages by returning their children
+        if (is_a($files, 'Kirby\Cms\Site') === true) {
+            $files = $files->files();
+        } elseif (is_a($files, 'Kirby\Cms\Page') === true) {
+            $files = $files->files();
+        } elseif (is_a($files, 'Kirby\Cms\User') === true) {
+            $files = $files->files();
+        } elseif (is_a($files, 'Kirby\Cms\Files') === false) {
+            throw new InvalidArgumentException('Your query must return a set of files');
+        }
+
+        // search
+        $files = $this->search($files);
+
+        // paginate
+        return $this->paginate($files);
+    }
+}

kirby/src/Cms/Filename.php

@@ -68,7 +68,7 @@ class Filename
      *
      * @param string $filename
      * @param string $template
-     * @param array  $attributes
+     * @param array $attributes
      */
     public function __construct(string $filename, string $template, array $attributes = [])
     {
@@ -118,7 +118,7 @@ class Filename
      * to a string, that can be used in the
      * new filename
      *
-     * @param  string $prefix The prefix will be used in the filename creation
+     * @param string $prefix The prefix will be used in the filename creation
      * @return string
      */
     public function attributesToString(string $prefix = null): string
@@ -265,7 +265,7 @@ class Filename
      * to lowercase and `jpeg` will be
      * replaced with `jpg`
      *
-     * @param  string $extension
+     * @param string $extension
      * @return string
      */
     protected function sanitizeExtension(string $extension): string
@@ -279,7 +279,7 @@ class Filename
      * Sanitizes the name with Kirby's
      * Str::slug function
      *
-     * @param  string $name
+     * @param string $name
      * @return string
      */
     protected function sanitizeName(string $name): string

kirby/src/Cms/HasChildren.php

@@ -157,7 +157,7 @@ trait HasChildren
     /**
      * Checks if the model has any children
      *
-     * @return boolean
+     * @return bool
      */
     public function hasChildren(): bool
     {
@@ -167,7 +167,7 @@ trait HasChildren
     /**
      * Checks if the model has any drafts
      *
-     * @return boolean
+     * @return bool
      */
     public function hasDrafts(): bool
     {
@@ -175,18 +175,20 @@ trait HasChildren
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::hasUnlistedChildren` instead
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasUnlistedChildren()` instead
+     * @return bool
      */
     public function hasInvisibleChildren(): bool
     {
+        deprecated('$page->hasInvisibleChildren() is deprecated, use $page->hasUnlistedChildren() instead. $page->hasInvisibleChildren() will be removed in Kirby 3.5.0.');
+
         return $this->hasUnlistedChildren();
     }
 
     /**
      * Checks if the page has any listed children
      *
-     * @return boolean
+     * @return bool
      */
     public function hasListedChildren(): bool
     {
@@ -196,7 +198,7 @@ trait HasChildren
     /**
      * Checks if the page has any unlisted children
      *
-     * @return boolean
+     * @return bool
      */
     public function hasUnlistedChildren(): bool
     {
@@ -204,11 +206,13 @@ trait HasChildren
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::hasListedChildren` instead
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasListedChildren()` instead
+     * @return bool
      */
     public function hasVisibleChildren(): bool
     {
+        deprecated('$page->hasVisibleChildren() is deprecated, use $page->hasListedChildren() instead. $page->hasVisibleChildren() will be removed in Kirby 3.5.0.');
+
         return $this->hasListedChildren();
     }
 

kirby/src/Cms/HasMethods.php

@@ -25,8 +25,8 @@ trait HasMethods
      * passed arguments
      *
      * @internal
-     * @param  string $method
-     * @param  array  $args
+     * @param string $method
+     * @param array $args
      * @return mixed
      */
     public function callMethod(string $method, array $args = [])
@@ -39,7 +39,7 @@ trait HasMethods
      *
      * @internal
      * @param string $method
-     * @return boolean
+     * @return bool
      */
     public function hasMethod(string $method): bool
     {

kirby/src/Cms/Language.php

@@ -58,6 +58,11 @@ class Language extends Model
      */
     protected $slugs;
 
+    /**
+     * @var array|null
+     */
+    protected $smartypants;
+
     /**
      * @var array|null
      */
@@ -85,6 +90,7 @@ class Language extends Model
             'locale',
             'name',
             'slugs',
+            'smartypants',
             'translations',
             'url',
         ]);
@@ -111,6 +117,28 @@ class Language extends Model
         return $this->code();
     }
 
+    /**
+     * Returns the base Url for the language
+     * without the path or other cruft
+     *
+     * @return string
+     */
+    public function baseUrl(): string
+    {
+        $kirbyUrl    = $this->kirby()->url();
+        $languageUrl = $this->url();
+
+        if (empty($this->url)) {
+            return $kirbyUrl;
+        }
+
+        if (Str::startsWith($languageUrl, $kirbyUrl) === true) {
+            return $kirbyUrl;
+        }
+
+        return Url::base($languageUrl) ?? $kirbyUrl;
+    }
+
     /**
      * Returns the language code/id.
      * The language code is used in
@@ -129,7 +157,7 @@ class Language extends Model
      *
      * @param string $from
      * @param string $to
-     * @return boolean
+     * @return bool
      */
     protected static function converter(string $from, string $to): bool
     {
@@ -201,7 +229,7 @@ class Language extends Model
      * all its translation files
      *
      * @internal
-     * @return boolean
+     * @return bool
      */
     public function delete(): bool
     {
@@ -270,7 +298,7 @@ class Language extends Model
     /**
      * Check if the language file exists
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -281,7 +309,7 @@ class Language extends Model
      * Checks if this is the default language
      * for the site.
      *
-     * @return boolean
+     * @return bool
      */
     public function isDefault(): bool
     {
@@ -325,6 +353,20 @@ class Language extends Model
         return $this->name;
     }
 
+    /**
+     * Returns the URL path for the language
+     *
+     * @return string
+     */
+    public function path(): string
+    {
+        if ($this->url === null) {
+            return $this->code;
+        }
+
+        return Url::path($this->url());
+    }
+
     /**
      * Returns the routing pattern for the language
      *
@@ -332,11 +374,13 @@ class Language extends Model
      */
     public function pattern(): string
     {
-        if (empty($this->url) === true) {
-            return $this->code;
+        $path = $this->path();
+
+        if (empty($path) === true) {
+            return '(:all)';
         }
 
-        return trim($this->url, '/');
+        return $path . '/(:all?)';
     }
 
     /**
@@ -430,7 +474,7 @@ class Language extends Model
     }
 
     /**
-     * @param boolean $default
+     * @param bool $default
      * @return self
      */
     protected function setDefault(bool $default = false)
@@ -488,6 +532,16 @@ class Language extends Model
         return $this;
     }
 
+    /**
+     * @param array $smartypants
+     * @return self
+     */
+    protected function setSmartypants(array $smartypants = null)
+    {
+        $this->smartypants = $smartypants ?? [];
+        return $this;
+    }
+
     /**
      * @param array $translations
      * @return self
@@ -518,6 +572,16 @@ class Language extends Model
         return $this->slugs;
     }
 
+    /**
+     * Returns the custom SmartyPants options for this language
+     *
+     * @return array
+     */
+    public function smartypants(): array
+    {
+        return $this->smartypants;
+    }
+
     /**
      * Returns the most important
      * properties as array
@@ -554,7 +618,13 @@ class Language extends Model
      */
     public function url(): string
     {
-        return Url::makeAbsolute($this->pattern(), $this->kirby()->url());
+        $url = $this->url;
+
+        if ($url === null) {
+            $url = '/' . $this->code;
+        }
+
+        return Url::makeAbsolute($url, $this->kirby()->url());
     }
 
     /**

kirby/src/Cms/LanguageRoutes.php

@@ -0,0 +1,143 @@
+<?php
+
+namespace Kirby\Cms;
+
+use Kirby\Toolkit\F;
+
+class LanguageRoutes
+{
+    /**
+     * Creates all multi-language routes
+     *
+     * @param \Kirby\Cms\App $kirby
+     * @return array
+     */
+    public static function create(App $kirby): array
+    {
+        $routes = [];
+
+        // add the route for the home page
+        $routes[] = static::home($kirby);
+
+        // Kirby's base url
+        $baseurl = $kirby->url();
+
+        foreach ($kirby->languages() as $language) {
+
+            // ignore languages with a different base url
+            if ($language->baseurl() !== $baseurl) {
+                continue;
+            }
+
+            $routes[] = [
+                'pattern' => $language->pattern(),
+                'method'  => 'ALL',
+                'env'     => 'site',
+                'action'  => function ($path = null) use ($language) {
+                    if ($result = $language->router()->call($path)) {
+                        return $result;
+                    }
+
+                    // jump through to the fallback if nothing
+                    // can be found for this language
+                    $this->next();
+                }
+            ];
+        }
+
+        $routes[] = static::fallback($kirby);
+
+        return $routes;
+    }
+
+
+    /**
+     * Create the fallback route
+     * for unprefixed default language URLs.
+     *
+     * @param \Kirby\Cms\App $kirby
+     * @return array
+     */
+    public static function fallback(App $kirby): array
+    {
+        return [
+            'pattern' => '(:all)',
+            'method'  => 'ALL',
+            'env'     => 'site',
+            'action'  => function (string $path) use ($kirby) {
+
+                // check for content representations or files
+                $extension = F::extension($path);
+
+                // try to redirect prefixed pages
+                if (empty($extension) === true && $page = $kirby->page($path)) {
+                    $url = $kirby->request()->url([
+                        'query'    => null,
+                        'params'   => null,
+                        'fragment' => null
+                    ]);
+
+                    if ($url->toString() !== $page->url()) {
+                        return $kirby
+                            ->response()
+                            ->redirect($page->url());
+                    }
+                }
+
+                return $kirby->defaultLanguage()->router()->call($path);
+            }
+        ];
+    }
+
+    /**
+     * Create the multi-language home page route
+     *
+     * @param \Kirby\Cms\App $kirby
+     * @return array
+     */
+    public static function home(App $kirby): array
+    {
+        // Multi-language home
+        return [
+            'pattern' => '',
+            'method'  => 'ALL',
+            'env'     => 'site',
+            'action'  => function () use ($kirby) {
+
+                // find all languages with the same base url as the current installation
+                $languages = $kirby->languages()->filterBy('baseurl', $kirby->url());
+
+                // if there's no language with a matching base url,
+                // redirect to the default language
+                if ($languages->count() === 0) {
+                    return $kirby
+                        ->response()
+                        ->redirect($kirby->defaultLanguage()->url());
+                }
+
+                // if there's just one language, we take that to render the home page
+                if ($languages->count() === 1) {
+                    $currentLanguage = $languages->first();
+                } else {
+                    $currentLanguage = $kirby->defaultLanguage();
+                }
+
+                // language detection on the home page with / as URL
+                if ($kirby->url() !== $currentLanguage->url()) {
+                    if ($kirby->option('languages.detect') === true) {
+                        return $kirby
+                            ->response()
+                            ->redirect($kirby->detectedLanguage()->url());
+                    }
+
+                    return $kirby
+                        ->response()
+                        ->redirect($currentLanguage->url());
+                }
+
+                // render the home page of the current language
+                return $currentLanguage->router()->call();
+            }
+        ];
+    }
+}

kirby/src/Cms/Languages.php

@@ -72,11 +72,13 @@ class Languages extends Collection
     }
 
     /**
-     * @deprecated 3.0.0  Use `Languages::default()`instead
+     * @deprecated 3.0.0  Use `Languages::default()` instead
      * @return \Kirby\Cms\Language|null
      */
     public function findDefault()
     {
+        deprecated('$languages->findDefault() is deprecated, use $languages->default() instead. $languages->findDefault() will be removed in Kirby 3.5.0.');
+
         return $this->default();
     }
 

kirby/src/Cms/Media.php

@@ -59,7 +59,7 @@ class Media
      *
      * @param string $src
      * @param string $dest
-     * @return boolean
+     * @return bool
      */
     public static function publish(string $src, string $dest): bool
     {

kirby/src/Cms/ModelWithContent.php

@@ -19,6 +19,14 @@ use Throwable;
  */
 abstract class ModelWithContent extends Model
 {
+    /**
+     * Each model must define a CLASS_ALIAS
+     * which will be used in template queries.
+     * The CLASS_ALIAS is a short human-readable
+     * version of the class name. I.e. page.
+     */
+    const CLASS_ALIAS = null;
+
     /**
      * The content
      *
@@ -194,8 +202,8 @@ abstract class ModelWithContent extends Model
      * Decrement a given field value
      *
      * @param string $field
-     * @param integer $by
-     * @param integer $min
+     * @param int $by
+     * @param int $min
      * @return self
      */
     public function decrement(string $field, int $by = 1, int $min = 0)
@@ -231,8 +239,8 @@ abstract class ModelWithContent extends Model
      * Increment a given field value
      *
      * @param string $field
-     * @param integer $by
-     * @param integer $max
+     * @param int $by
+     * @param int $max
      * @return self
      */
     public function increment(string $field, int $by = 1, int $max = null)
@@ -246,10 +254,21 @@ abstract class ModelWithContent extends Model
         return $this->update([$field => $value]);
     }
 
+    /**
+     * Checks if the model is locked for the current user
+     *
+     * @return bool
+     */
+    public function isLocked(): bool
+    {
+        $lock = $this->lock();
+        return $lock && $lock->isLocked() === true;
+    }
+
     /**
      * Checks if the data has any errors
      *
-     * @return boolean
+     * @return bool
      */
     public function isValid(): bool
     {
@@ -382,6 +401,38 @@ abstract class ModelWithContent extends Model
         return $image;
     }
 
+    /**
+     * Returns an array of all actions
+     * that can be performed in the Panel
+     * This also checks for the lock status
+     *
+     * @param array $unlock An array of options that will be force-unlocked
+     * @return array
+     */
+    public function panelOptions(array $unlock = []): array
+    {
+        $options = $this->permissions()->toArray();
+
+        if ($this->isLocked()) {
+            foreach ($options as $key => $value) {
+                if (in_array($key, $unlock)) {
+                    continue;
+                }
+
+                $options[$key] = false;
+            }
+        }
+
+        return $options;
+    }
+
+    /**
+     * Must return the permissions object for the model
+     *
+     * @return \Kirby\Cms\ModelPermissions
+     */
+    abstract public function permissions();
+
     /**
      * Creates a string query, starting from the model
      *
@@ -618,7 +669,7 @@ abstract class ModelWithContent extends Model
      *
      * @param array $input
      * @param string $languageCode
-     * @param boolean $validate
+     * @param bool $validate
      * @return self
      */
     public function update(array $input = null, string $languageCode = null, bool $validate = false)
@@ -657,7 +708,7 @@ abstract class ModelWithContent extends Model
      * @internal
      * @param array $data
      * @param string $languageCode
-     * @return boolean
+     * @return bool
      */
     public function writeContent(array $data, string $languageCode = null): bool
     {

kirby/src/Cms/NestCollection.php

@@ -21,7 +21,7 @@ class NestCollection extends BaseCollection
      * to an array. This can also take a callback
      * function to further modify the array result.
      *
-     * @param  Closure $map
+     * @param Closure $map
      * @return array
      */
     public function toArray(Closure $map = null): array

kirby/src/Cms/Page.php

@@ -104,7 +104,7 @@ class Page extends ModelWithContent
     /**
      * The sorting number
      *
-     * @var integer|null
+     * @var int|null
      */
     protected $num;
 
@@ -253,15 +253,14 @@ class Page extends ModelWithContent
             $templates = [];
         }
 
-        // add the current template to the array
-        $templates[] = $currentTemplate;
+        // add the current template to the array if it's not already there
+        if (in_array($currentTemplate, $templates) === false) {
+            array_unshift($templates, $currentTemplate);
+        }
 
         // make sure every template is only included once
         $templates = array_unique($templates);
 
-        // sort the templates
-        asort($templates);
-
         foreach ($templates as $template) {
             try {
                 $props = Blueprint::load('pages/' . $template);
@@ -352,7 +351,7 @@ class Page extends ModelWithContent
      * Returns a number indicating how deep the page
      * is nested within the content folder
      *
-     * @return integer
+     * @return int
      */
     public function depth(): int
     {
@@ -408,11 +407,13 @@ class Page extends ModelWithContent
      * gets dragged onto a textarea
      *
      * @internal
-     * @param string $type (auto|kirbytext|markdown)
+     * @param string $type (null|auto|kirbytext|markdown)
      * @return string
      */
-    public function dragText(string $type = 'auto'): string
+    public function dragText(string $type = null): string
     {
+        $type = $type ?? 'auto';
+
         if ($type === 'auto') {
             $type = option('panel.kirbytext', true) ? 'kirbytext' : 'markdown';
         }
@@ -456,7 +457,7 @@ class Page extends ModelWithContent
      * Checks if the intended template
      * for the page exists.
      *
-     * @return boolean
+     * @return bool
      */
     public function hasTemplate(): bool
     {
@@ -563,7 +564,7 @@ class Page extends ModelWithContent
      * Checks if the page is a direct or indirect ancestor of the given $page object
      *
      * @param Page $child
-     * @return boolean
+     * @return bool
      */
     public function isAncestorOf(Page $child): bool
     {
@@ -575,7 +576,7 @@ class Page extends ModelWithContent
      * pages cache. This will also check if one
      * of the ignore rules from the config kick in.
      *
-     * @return boolean
+     * @return bool
      */
     public function isCacheable(): bool
     {
@@ -628,12 +629,12 @@ class Page extends ModelWithContent
      * Checks if the page is a child of the given page
      *
      * @param \Kirby\Cms\Page|string $parent
-     * @return boolean
+     * @return bool
      */
     public function isChildOf($parent): bool
     {
-        if ($parent = $this->parent()) {
-            return $parent->is($parent);
+        if ($parentObj = $this->parent()) {
+            return $parentObj->is($parent);
         }
 
         return false;
@@ -643,7 +644,7 @@ class Page extends ModelWithContent
      * Checks if the page is a descendant of the given page
      *
      * @param \Kirby\Cms\Page|string $parent
-     * @return boolean
+     * @return bool
      */
     public function isDescendantOf($parent): bool
     {
@@ -661,7 +662,7 @@ class Page extends ModelWithContent
     /**
      * Checks if the page is a descendant of the currently active page
      *
-     * @return boolean
+     * @return bool
      */
     public function isDescendantOfActive(): bool
     {
@@ -675,7 +676,7 @@ class Page extends ModelWithContent
     /**
      * Checks if the current page is a draft
      *
-     * @return boolean
+     * @return bool
      */
     public function isDraft(): bool
     {
@@ -695,7 +696,7 @@ class Page extends ModelWithContent
     /**
      * Check if the page can be read by the current user
      *
-     * @return boolean
+     * @return bool
      */
     public function isReadable(): bool
     {
@@ -725,7 +726,7 @@ class Page extends ModelWithContent
      * home and error page to stop certain
      * actions. That's why there's a shortcut.
      *
-     * @return boolean
+     * @return bool
      */
     public function isHomeOrErrorPage(): bool
     {
@@ -733,18 +734,20 @@ class Page extends ModelWithContent
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::isUnlisted()` intead
+     * @deprecated 3.0.0 Use `Page::isUnlisted()` instead
      * @return bool
      */
     public function isInvisible(): bool
     {
+        deprecated('$page->isInvisible() is deprecated, use $page->isUnlisted() instead. $page->isInvisible() will be removed in Kirby 3.5.0.');
+
         return $this->isUnlisted();
     }
 
     /**
      * Checks if the page has a sorting number
      *
-     * @return boolean
+     * @return bool
      */
     public function isListed(): bool
     {
@@ -776,7 +779,7 @@ class Page extends ModelWithContent
     /**
      * Checks if the page is sortable
      *
-     * @return boolean
+     * @return bool
      */
     public function isSortable(): bool
     {
@@ -786,7 +789,7 @@ class Page extends ModelWithContent
     /**
      * Checks if the page has no sorting number
      *
-     * @return boolean
+     * @return bool
      */
     public function isUnlisted(): bool
     {
@@ -794,11 +797,13 @@ class Page extends ModelWithContent
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::isListed()` intead
+     * @deprecated 3.0.0 Use `Page::isListed()` instead
      * @return bool
      */
     public function isVisible(): bool
     {
+        deprecated('$page->isVisible() is deprecated, use $page->isListed() instead. $page->isVisible() will be removed in Kirby 3.5.0.');
+
         return $this->isListed();
     }
 
@@ -808,7 +813,7 @@ class Page extends ModelWithContent
      *
      * @internal
      * @param string $token
-     * @return boolean
+     * @return bool
      */
     public function isVerified(string $token = null)
     {
@@ -884,7 +889,7 @@ class Page extends ModelWithContent
     /**
      * Returns the sorting number
      *
-     * @return integer|null
+     * @return int|null
      */
     public function num(): ?int
     {
@@ -1099,7 +1104,7 @@ class Page extends ModelWithContent
      *
      * @param array $data
      * @param string $contentType
-     * @param integer $code
+     * @param int $code
      * @return string
      */
     public function render(array $data = [], $contentType = 'html'): string
@@ -1241,7 +1246,7 @@ class Page extends ModelWithContent
     /**
      * Sets the draft flag
      *
-     * @param boolean $isDraft
+     * @param bool $isDraft
      * @return self
      */
     protected function setIsDraft(bool $isDraft = null)
@@ -1253,7 +1258,7 @@ class Page extends ModelWithContent
     /**
      * Sets the sorting number
      *
-     * @param integer $num
+     * @param int $num
      * @return self
      */
     protected function setNum(int $num = null)

kirby/src/Cms/PageActions.php

@@ -160,7 +160,7 @@ trait PageActions
      * to either draft, listed or unlisted
      *
      * @param string $status "draft", "listed" or "unlisted"
-     * @param integer $position Optional sorting number
+     * @param int $position Optional sorting number
      * @return self
      */
     public function changeStatus(string $status, int $position = null)
@@ -462,8 +462,8 @@ trait PageActions
      * Create the sorting number for the page
      * depending on the blueprint settings
      *
-     * @param integer $num
-     * @return integer
+     * @param int $num
+     * @return int
      */
     public function createNum(int $num = null): int
     {
@@ -631,12 +631,13 @@ trait PageActions
      */
     public function purge()
     {
-        $this->children  = null;
-        $this->blueprint = null;
-        $this->drafts    = null;
-        $this->files     = null;
-        $this->content   = null;
-        $this->inventory = null;
+        $this->blueprint    = null;
+        $this->children     = null;
+        $this->content      = null;
+        $this->drafts       = null;
+        $this->files        = null;
+        $this->inventory    = null;
+        $this->translations = null;
 
         return $this;
     }
@@ -756,7 +757,7 @@ trait PageActions
      *
      * @param array $input
      * @param string $language
-     * @param boolean $validate
+     * @param bool $validate
      * @return self
      */
     public function update(array $input = null, string $language = null, bool $validate = false)

kirby/src/Cms/PageBlueprint.php

@@ -75,7 +75,6 @@ class PageBlueprint extends Blueprint
     protected function normalizeNum($num): string
     {
         $aliases = [
-            0      => 'zero',
             '0'    => 'zero',
             'sort' => 'default',
         ];
@@ -185,7 +184,7 @@ class PageBlueprint extends Blueprint
      * button in the panel and redirects it to a
      * different URL if necessary.
      *
-     * @return string|boolean
+     * @return string|bool
      */
     public function preview()
     {

kirby/src/Cms/PagePicker.php

@@ -0,0 +1,264 @@
+<?php
+
+namespace Kirby\Cms;
+
+use Kirby\Exception\InvalidArgumentException;
+
+/**
+ * The PagePicker class helps to
+ * fetch the right pages and the parent
+ * model for the API calls for the
+ * page picker component in the panel.
+ *
+ * @package   Kirby Cms
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://getkirby.com/license
+ */
+class PagePicker extends Picker
+{
+    /**
+     * @var \Kirby\Cms\Pages
+     */
+    protected $items;
+
+    /**
+     * @var \Kirby\Cms\Pages
+     */
+    protected $itemsForQuery;
+
+    /**
+     * @var \Kirby\Cms\Page|\Kirby\Cms\Site|null
+     */
+    protected $parent;
+
+    /**
+     * Extends the basic defaults
+     *
+     * @return array
+     */
+    public function defaults(): array
+    {
+        return array_merge(parent::defaults(), [
+            // Page ID of the selected parent. Used to navigate
+            'parent' => null,
+            // enable/disable subpage navigation
+            'subpages' => true,
+        ]);
+    }
+
+    /**
+     * Returns the parent model object that
+     * is currently selected in the page picker.
+     * It normally starts at the site, but can
+     * also be any subpage. When a query is given
+     * and subpage navigation is deactivated,
+     * there will be no model available at all.
+     *
+     * @return \Kirby\Cms\Page|\Kirby\Cms\Site|null
+     */
+    public function model()
+    {
+        // no subpages navigation = no model
+        if ($this->options['subpages'] === false) {
+            return null;
+        }
+
+        // the model for queries is a bit more tricky to find
+        if (empty($this->options['query']) === false) {
+            return $this->modelForQuery();
+        }
+
+        return $this->parent();
+    }
+
+    /**
+     * Returns a model object for the given
+     * query, depending on the parent and subpages
+     * options.
+     *
+     * @return \Kirby\Cms\Page|\Kirby\Cms\Site|null
+     */
+    public function modelForQuery()
+    {
+        if ($this->options['subpages'] === true && empty($this->options['parent']) === false) {
+            return $this->parent();
+        }
+
+        if ($items = $this->items()) {
+            return $items->parent();
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns basic information about the
+     * parent model that is currently selected
+     * in the page picker.
+     *
+     * @param \Kirby\Cms\Site|\Kirby\Cms\Page|null
+     * @return array|null
+     */
+    public function modelToArray($model = null): ?array
+    {
+        if ($model === null) {
+            return null;
+        }
+
+        // the selected model is the site. there's nothing above
+        if (is_a($model, 'Kirby\Cms\Site') === true) {
+            return [
+                'id'     => null,
+                'parent' => null,
+                'title'  => $model->title()->value()
+            ];
+        }
+
+        // the top-most page has been reached
+        // the missing id indicates that there's nothing above
+        if ($model->id() === $this->start()->id()) {
+            return [
+                'id'     => null,
+                'parent' => null,
+                'title'  => $model->title()->value()
+            ];
+        }
+
+        // the model is a regular page
+        return [
+            'id'     => $model->id(),
+            'parent' => $model->parentModel()->id(),
+            'title'  => $model->title()->value()
+        ];
+    }
+
+    /**
+     * Search all pages for the picker
+     *
+     * @return \Kirby\Cms\Pages|null
+     */
+    public function items()
+    {
+        // cache
+        if ($this->items !== null) {
+            return $this->items;
+        }
+
+        // no query? simple parent-based search for pages
+        if (empty($this->options['query']) === true) {
+            $items = $this->itemsForParent();
+
+        // when subpage navigation is enabled, a parent
+        // might be passed in addition to the query.
+        // The parent then takes priority.
+        } elseif ($this->options['subpages'] === true && empty($this->options['parent']) === false) {
+            $items = $this->itemsForParent();
+
+        // search by query
+        } else {
+            $items = $this->itemsForQuery();
+        }
+
+        // filter protected pages
+        $items = $items->filterBy('isReadable', true);
+
+        // search
+        $items = $this->search($items);
+
+        // paginate the result
+        return $this->items = $this->paginate($items);
+    }
+
+    /**
+     * Search for pages by parent
+     *
+     * @return \Kirby\Cms\Pages
+     */
+    public function itemsForParent()
+    {
+        return $this->parent()->children();
+    }
+
+    /**
+     * Search for pages by query string
+     *
+     * @return \Kirby\Cms\Pages
+     */
+    public function itemsForQuery()
+    {
+        // cache
+        if ($this->itemsForQuery !== null) {
+            return $this->itemsForQuery;
+        }
+
+        $model = $this->options['model'];
+        $items = $model->query($this->options['query']);
+
+        // help mitigate some typical query usage issues
+        // by converting site and page objects to proper
+        // pages by returning their children
+        if (is_a($items, 'Kirby\Cms\Site') === true) {
+            $items = $items->children();
+        } elseif (is_a($items, 'Kirby\Cms\Page') === true) {
+            $items = $items->children();
+        } elseif (is_a($items, 'Kirby\Cms\Pages') === false) {
+            throw new InvalidArgumentException('Your query must return a set of pages');
+        }
+
+        return $this->itemsForQuery = $items;
+    }
+
+    /**
+     * Returns the parent model.
+     * The model will be used to fetch
+     * subpages unless there's a specific
+     * query to find pages instead.
+     *
+     * @return \Kirby\Cms\Page|\Kirby\Cms\Site
+     */
+    public function parent()
+    {
+        if ($this->parent !== null) {
+            return $this->parent;
+        }
+
+        return $this->parent = $this->kirby->page($this->options['parent']) ?? $this->site;
+    }
+
+    /**
+     * Calculates the top-most model (page or site)
+     * that can be accessed when navigating
+     * through pages.
+     *
+     * @return \Kirby\Cms\Page|\Kirby\Cms\Site
+     */
+    public function start()
+    {
+        if (empty($this->options['query']) === false) {
+            if ($items = $this->itemsForQuery()) {
+                return $items->parent();
+            }
+
+            return $this->site;
+        }
+
+        return $this->site;
+    }
+
+    /**
+     * Returns an associative array
+     * with all information for the picker.
+     * This will be passed directly to the API.
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        $array = parent::toArray();
+        $array['model'] = $this->modelToArray($this->model());
+
+        return $array;
+    }
+}

kirby/src/Cms/PageRules.php

@@ -205,6 +205,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->exists() === true) {
             throw new DuplicateException([
                 'key'  => 'page.draft.duplicate',

kirby/src/Cms/PageSiblings.php

@@ -14,11 +14,13 @@ namespace Kirby\Cms;
 trait PageSiblings
 {
     /**
-     * @deprecated 3.0.0 Use `Page::hasNextUnlisted` instead
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasNextUnlisted()` instead
+     * @return bool
      */
     public function hasNextInvisible(): bool
     {
+        deprecated('$page->hasNextInvisible() is deprecated, use $page->hasNextUnlisted() instead. $page->hasNextInvisible() will be removed in Kirby 3.5.0.');
+
         return $this->hasNextUnlisted();
     }
 
@@ -45,20 +47,24 @@ trait PageSiblings
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::hasNextListed` instead
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasNextListed()` instead
+     * @return bool
      */
     public function hasNextVisible(): bool
     {
+        deprecated('$page->hasNextVisible() is deprecated, use $page->hasNextListed() instead. $page->hasNextVisible() will be removed in Kirby 3.5.0.');
+
         return $this->hasNextListed();
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::hasPrevUnlisted` instead
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasPrevUnlisted()` instead
+     * @return bool
      */
     public function hasPrevInvisible(): bool
     {
+        deprecated('$page->hasPrevInvisible() is deprecated, use $page->hasPrevUnlisted() instead. $page->hasPrevInvisible() will be removed in Kirby 3.5.0.');
+
         return $this->hasPrevUnlisted();
     }
 
@@ -85,11 +91,13 @@ trait PageSiblings
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::hasPrevListed instead`
-     * @return boolean
+     * @deprecated 3.0.0 Use `Page::hasPrevListed()` instead
+     * @return bool
      */
     public function hasPrevVisible(): bool
     {
+        deprecated('$page->hasPrevVisible() is deprecated, use $page->hasPrevListed() instead. $page->hasPrevVisible() will be removed in Kirby 3.5.0.');
+
         return $this->hasPrevListed();
     }
 
@@ -99,6 +107,8 @@ trait PageSiblings
      */
     public function nextInvisible()
     {
+        deprecated('$page->nextInvisible() is deprecated, use $page->nextUnlisted() instead. $page->nextInvisible() will be removed in Kirby 3.5.0.');
+
         return $this->nextUnlisted();
     }
 
@@ -123,11 +133,13 @@ trait PageSiblings
     }
 
     /**
-     * @deprecated 3.0.0 Use `Page::prevListed()` instead
+     * @deprecated 3.0.0 Use `Page::nextListed()` instead
      * @return self|null
      */
     public function nextVisible()
     {
+        deprecated('$page->nextVisible() is deprecated, use $page->nextListed() instead. $page->nextVisible() will be removed in Kirby 3.5.0.');
+
         return $this->nextListed();
     }
 
@@ -137,6 +149,8 @@ trait PageSiblings
      */
     public function prevInvisible()
     {
+        deprecated('$page->prevInvisible() is deprecated, use $page->prevUnlisted() instead. $page->prevInvisible() will be removed in Kirby 3.5.0.');
+
         return $this->prevUnlisted();
     }
 
@@ -166,6 +180,8 @@ trait PageSiblings
      */
     public function prevVisible()
     {
+        deprecated('$page->prevVisible() is deprecated, use $page->prevListed() instead. $page->prevVisible() will be removed in Kirby 3.5.0.');
+
         return $this->prevListed();
     }
 

kirby/src/Cms/Pages.php

@@ -2,6 +2,8 @@
 
 namespace Kirby\Cms;
 
+use Kirby\Exception\InvalidArgumentException;
+
 /**
  * The `$pages` object refers to a
  * collection of pages. The pages in this
@@ -55,6 +57,10 @@ class Pages extends Collection
         // add a page object
         } elseif (is_a($object, 'Kirby\Cms\Page') === true) {
             $this->__set($object->id(), $object);
+
+        // give a useful error message on invalid input
+        } elseif (in_array($object, [null, false, true], true) !== true) {
+            throw new InvalidArgumentException('You must pass a Page object to the Pages collection');
         }
 
         return $this;
@@ -344,13 +350,15 @@ class Pages extends Collection
     }
 
     /**
-     * Deprecated alias for Pages::unlisted()
+     * @deprecated 3.0.0 Use `Pages::unlisted()` instead
      *
      * @return self
      */
     public function invisible()
     {
-        return $this->filterBy('isUnlisted', '==', true);
+        deprecated('$pages->invisible() is deprecated, use $pages->unlisted() instead. $pages->invisible() will be removed in Kirby 3.5.0.');
+
+        return $this->unlisted();
     }
 
     /**
@@ -428,6 +436,27 @@ class Pages extends Collection
         return $this;
     }
 
+    /**
+     * Filter all pages by excluding the given template
+     *
+     * @param string|array $templates
+     * @return \Kirby\Cms\Pages
+     */
+    public function notTemplate($templates)
+    {
+        if (empty($templates) === true) {
+            return $this;
+        }
+
+        if (is_array($templates) === false) {
+            $templates = [$templates];
+        }
+
+        return $this->filter(function ($page) use ($templates) {
+            return !in_array($page->intendedTemplate()->name(), $templates);
+        });
+    }
+
     /**
      * Returns an array with all page numbers
      *
@@ -480,12 +509,14 @@ class Pages extends Collection
     }
 
     /**
-     * Deprecated alias for Pages::listed()
+     * @deprecated 3.0.0 Use `Pages::listed()` instead
      *
      * @return \Kirby\Cms\Pages
      */
     public function visible()
     {
-        return $this->filterBy('isListed', '==', true);
+        deprecated('$pages->visible() is deprecated, use $pages->listed() instead. $pages->visible() will be removed in Kirby 3.5.0.');
+
+        return $this->listed();
     }
 }

kirby/src/Cms/Pagination.php

@@ -81,9 +81,9 @@ class Pagination extends BasePagination
         }
 
         if ($params['method'] === 'query') {
-            $params['page'] = $params['page'] ?? $params['url']->query()->get($params['variable'], 1);
+            $params['page'] = $params['page'] ?? $params['url']->query()->get($params['variable']);
         } else {
-            $params['page'] = $params['page'] ?? $params['url']->params()->get($params['variable'], 1);
+            $params['page'] = $params['page'] ?? $params['url']->params()->get($params['variable']);
         }
 
         parent::__construct($params);

kirby/src/Cms/Panel.php

@@ -107,6 +107,7 @@ class Panel
             'pluginCss' => $plugins->url('css'),
             'pluginJs'  => $plugins->url('js'),
             'panelUrl'  => $uri->path()->toString(true) . '/',
+            'nonce'     => $kirby->nonce(),
             'options'   => [
                 'url'         => $url,
                 'site'        => $kirby->url('index'),

kirby/src/Cms/Picker.php

@@ -0,0 +1,176 @@
+<?php
+
+namespace Kirby\Cms;
+
+/**
+ * The Picker abstract is the foundation
+ * for the UserPicker, PagePicker and FilePicker
+ *
+ * @package   Kirby Cms
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://getkirby.com/license
+ */
+abstract class Picker
+{
+    /**
+     * @var \Kirby\Cms\App
+     */
+    protected $kirby;
+
+    /**
+     * @var array
+     */
+    protected $options;
+
+    /**
+     * @var \Kirby\Cms\Site
+     */
+    protected $site;
+
+    /**
+     * Creates a new Picker instance
+     *
+     * @param array $params
+     */
+    public function __construct(array $params = [])
+    {
+        $this->options = array_merge($this->defaults(), $params);
+        $this->kirby   = $this->options['model']->kirby();
+        $this->site    = $this->kirby->site();
+    }
+
+    /**
+     * Return the array of default values
+     *
+     * @return array
+     */
+    protected function defaults(): array
+    {
+        // default params
+        return [
+            // image settings (ratio, cover, etc.)
+            'image' => [],
+            // query template for the info field
+            'info' => false,
+            // number of users displayed per pagination page
+            'limit' => 20,
+            // optional mapping function for the result array
+            'map' => null,
+            // the reference model
+            'model' => site(),
+            // current page when paginating
+            'page' => 1,
+            // a query string to fetch specific items
+            'query' => null,
+            // search query
+            'search' => null,
+            // query template for the text field
+            'text' =>  null
+        ];
+    }
+
+    /**
+     * Fetches all items for the picker
+     *
+     * @return \Kirby\Cms\Collection|null
+     */
+    abstract public function items();
+
+    /**
+     * Converts all given items to an associative
+     * array that is already optimized for the
+     * panel picker component.
+     *
+     * @param \Kirby\Cms\Collection|null $items
+     * @return array
+     */
+    public function itemsToArray($items = null): array
+    {
+        if ($items === null) {
+            return [];
+        }
+
+        $result = [];
+
+        foreach ($items as $index => $item) {
+            if (empty($this->options['map']) === false) {
+                $result[] = $this->options['map']($item);
+            } else {
+                $result[] = $item->panelPickerData([
+                    'image' => $this->options['image'],
+                    'info'  => $this->options['info'],
+                    'model' => $this->options['model'],
+                    'text'  => $this->options['text'],
+                ]);
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Apply pagination to the collection
+     * of items according to the options.
+     *
+     * @param \Kirby\Cms\Collection $items
+     * @return \Kirby\Cms\Collection
+     */
+    public function paginate($items)
+    {
+        return $items->paginate([
+            'limit' => $this->options['limit'],
+            'page'  => $this->options['page']
+        ]);
+    }
+
+    /**
+     * Return the most relevant pagination
+     * info as array
+     *
+     * @param \Kirby\Cms\Pagination $pagination
+     * @return array
+     */
+    public function paginationToArray(Pagination $pagination): array
+    {
+        return [
+            'limit' => $pagination->limit(),
+            'page'  => $pagination->page(),
+            'total' => $pagination->total()
+        ];
+    }
+
+    /**
+     * Search through the collection of items
+     * if not deactivate in the options
+     *
+     * @param \Kirby\Cms\Collection $items
+     * @return \Kirby\Cms\Collection
+     */
+    public function search($items)
+    {
+        if (empty($this->options['search']) === false) {
+            return $items->search($this->options['search']);
+        }
+
+        return $items;
+    }
+
+    /**
+     * Returns an associative array
+     * with all information for the picker.
+     * This will be passed directly to the API.
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        $items = $this->items();
+
+        return [
+            'data'       => $this->itemsToArray($items),
+            'pagination' => $this->paginationToArray($items->pagination()),
+        ];
+    }
+}

kirby/src/Cms/Responder.php

@@ -19,7 +19,7 @@ class Responder
     /**
      * HTTP status code
      *
-     * @var integer
+     * @var int
      */
     protected $code = null;
 
@@ -73,8 +73,8 @@ class Responder
     /**
      * Setter and getter for the status code
      *
-     * @param integer $code
-     * @return integer|self
+     * @param int $code
+     * @return int|self
      */
     public function code(int $code = null)
     {
@@ -156,7 +156,7 @@ class Responder
      * Shortcut to create a redirect response
      *
      * @param string|null $location
-     * @param integer|null $code
+     * @param int|null $code
      * @return self
      */
     public function redirect(?string $location = null, ?int $code = null)

kirby/src/Cms/Roles.php

@@ -29,8 +29,8 @@ class Roles extends Collection
      */
     public function canBeChanged()
     {
-        if ($user = App::instance()->user()) {
-            return $this->filter(function ($role) use ($user) {
+        if (App::instance()->user()) {
+            return $this->filter(function ($role) {
                 $newUser = new User([
                     'email' => 'test@getkirby.com',
                     'role'  => $role->id()
@@ -52,8 +52,8 @@ class Roles extends Collection
      */
     public function canBeCreated()
     {
-        if ($user = App::instance()->user()) {
-            return $this->filter(function ($role) use ($user) {
+        if (App::instance()->user()) {
+            return $this->filter(function ($role) {
                 $newUser = new User([
                     'email' => 'test@getkirby.com',
                     'role'  => $role->id()

kirby/src/Cms/Search.php

@@ -73,6 +73,7 @@ class Search
             $keys[] = 'id';
 
             if (is_a($item, 'Kirby\Cms\User') === true) {
+                $keys[] = 'name';
                 $keys[] = 'email';
                 $keys[] = 'role';
             } elseif (is_a($item, 'Kirby\Cms\Page') === true) {

kirby/src/Cms/Site.php

@@ -273,7 +273,7 @@ class Site extends ModelWithContent
     /**
      * Checks if the site exists on disk
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -391,7 +391,7 @@ class Site extends ModelWithContent
      * prop, the home page will be returned if
      * it can be found. (see `Site::homePage()`)
      *
-     * @param  string $path
+     * @param string $path
      * @return \Kirby\Cms\Page|null
      */
     public function page(string $path = null)
@@ -645,8 +645,8 @@ class Site extends ModelWithContent
      * returns the current page
      *
      * @internal
-     * @param  string|\Kirby\Cms\Page $page
-     * @param  string|null $languageCode
+     * @param string|\Kirby\Cms\Page $page
+     * @param string|null $languageCode
      * @return \Kirby\Cms\Page
      */
     public function visit($page, string $languageCode = null)

kirby/src/Cms/SiteActions.php

@@ -81,11 +81,12 @@ trait SiteActions
      */
     public function purge()
     {
-        $this->children  = null;
-        $this->blueprint = null;
-        $this->files     = null;
-        $this->content   = null;
-        $this->inventory = null;
+        $this->blueprint    = null;
+        $this->children     = null;
+        $this->content      = null;
+        $this->files        = null;
+        $this->inventory    = null;
+        $this->translations = null;
 
         return $this;
     }

kirby/src/Cms/SiteBlueprint.php

@@ -45,7 +45,7 @@ class SiteBlueprint extends Blueprint
      * button in the panel and redirects it to a
      * different URL if necessary.
      *
-     * @return string|boolean
+     * @return string|bool
      */
     public function preview()
     {

kirby/src/Cms/SiteRules.php

@@ -2,7 +2,9 @@
 
 namespace Kirby\Cms;
 
+use Kirby\Exception\InvalidArgumentException;
 use Kirby\Exception\PermissionException;
+use Kirby\Toolkit\Str;
 
 /**
  * Validators for all site actions
@@ -21,6 +23,10 @@ class SiteRules
             throw new PermissionException(['key' => 'site.changeTitle.permission']);
         }
 
+        if (Str::length($title) === 0) {
+            throw new InvalidArgumentException(['key' => 'site.changeTitle.empty']);
+        }
+
         return true;
     }
 

kirby/src/Cms/System.php

@@ -79,7 +79,7 @@ class System
     /**
      * Check for a writable accounts folder
      *
-     * @return boolean
+     * @return bool
      */
     public function accounts(): bool
     {
@@ -89,7 +89,7 @@ class System
     /**
      * Check for a writable content folder
      *
-     * @return boolean
+     * @return bool
      */
     public function content(): bool
     {
@@ -99,7 +99,7 @@ class System
     /**
      * Check for an existing curl extension
      *
-     * @return boolean
+     * @return bool
      */
     public function curl(): bool
     {
@@ -165,7 +165,7 @@ class System
      * option must be explicitly set to true
      * to get the installer up and running.
      *
-     * @return boolean
+     * @return bool
      */
     public function isInstallable(): bool
     {
@@ -175,7 +175,7 @@ class System
     /**
      * Check if Kirby is already installed
      *
-     * @return boolean
+     * @return bool
      */
     public function isInstalled(): bool
     {
@@ -185,7 +185,7 @@ class System
     /**
      * Check if this is a local installation
      *
-     * @return boolean
+     * @return bool
      */
     public function isLocal(): bool
     {
@@ -218,7 +218,7 @@ class System
     /**
      * Check if all tests pass
      *
-     * @return boolean
+     * @return bool
      */
     public function isOk(): bool
     {
@@ -318,7 +318,7 @@ class System
     /**
      * Check for an existing mbstring extension
      *
-     * @return boolean
+     * @return bool
      */
     public function mbString(): bool
     {
@@ -328,7 +328,7 @@ class System
     /**
      * Check for a writable media folder
      *
-     * @return boolean
+     * @return bool
      */
     public function media(): bool
     {
@@ -338,7 +338,7 @@ class System
     /**
      * Check for a valid PHP version
      *
-     * @return boolean
+     * @return bool
      */
     public function php(): bool
     {
@@ -352,7 +352,7 @@ class System
      *
      * @param string $license
      * @param string $email
-     * @return boolean
+     * @return bool
      */
     public function register(string $license = null, string $email = null): bool
     {
@@ -404,7 +404,7 @@ class System
     /**
      * Check for a valid server environment
      *
-     * @return boolean
+     * @return bool
      */
     public function server(): bool
     {
@@ -424,7 +424,7 @@ class System
     /**
      * Check for a writable sessions folder
      *
-     * @return boolean
+     * @return bool
      */
     public function sessions(): bool
     {

kirby/src/Cms/Template.php

@@ -74,7 +74,7 @@ class Template
     /**
      * Checks if the template exists
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -190,7 +190,7 @@ class Template
     /**
      * Checks if the template uses the default type
      *
-     * @return boolean
+     * @return bool
      */
     public function hasDefaultType(): bool
     {

kirby/src/Cms/User.php

@@ -248,7 +248,7 @@ class User extends ModelWithContent
     /**
      * Checks if the user exists
      *
-     * @return boolean
+     * @return bool
      */
     public function exists(): bool
     {
@@ -342,7 +342,7 @@ class User extends ModelWithContent
     /**
      * Checks if this user has the admin role
      *
-     * @return boolean
+     * @return bool
      */
     public function isAdmin(): bool
     {
@@ -353,7 +353,7 @@ class User extends ModelWithContent
      * Checks if the current user is the virtual
      * Kirby user
      *
-     * @return boolean
+     * @return bool
      */
     public function isKirby(): bool
     {
@@ -363,7 +363,7 @@ class User extends ModelWithContent
     /**
      * Checks if the current user is this user
      *
-     * @return boolean
+     * @return bool
      */
     public function isLoggedIn(): bool
     {
@@ -374,7 +374,7 @@ class User extends ModelWithContent
      * Checks if the user is the last one
      * with the admin role
      *
-     * @return boolean
+     * @return bool
      */
     public function isLastAdmin(): bool
     {
@@ -384,7 +384,7 @@ class User extends ModelWithContent
     /**
      * Checks if the user is the last user
      *
-     * @return boolean
+     * @return bool
      */
     public function isLastUser(): bool
     {
@@ -426,10 +426,16 @@ class User extends ModelWithContent
      */
     public function loginPasswordless($session = null): void
     {
+        $kirby = $this->kirby();
+
         $session = $this->sessionFromOptions($session);
 
+        $kirby->trigger('user.login:before', $this, $session);
+
         $session->regenerateToken(); // privilege change
         $session->data()->set('user.id', $this->id());
+
+        $kirby->trigger('user.login:after', $this, $session);
     }
 
     /**
@@ -440,16 +446,23 @@ class User extends ModelWithContent
      */
     public function logout($session = null): void
     {
+        $kirby   = $this->kirby();
         $session = $this->sessionFromOptions($session);
 
+        $kirby->trigger('user.logout:before', $this, $session);
+
         $session->data()->remove('user.id');
 
         if ($session->data()->get() === []) {
             // session is now empty, we might as well destroy it
             $session->destroy();
+
+            $kirby->trigger('user.logout:after', $this, null);
         } else {
             // privilege change
             $session->regenerateToken();
+
+            $kirby->trigger('user.logout:after', $this, $session);
         }
     }
 
@@ -857,7 +870,7 @@ class User extends ModelWithContent
      * Compares the given password with the stored one
      *
      * @param string $password
-     * @return boolean
+     * @return bool
      *
      * @throws NotFoundException If the user has no password
      * @throws InvalidArgumentException If the entered password is not valid

kirby/src/Cms/UserActions.php

@@ -293,7 +293,7 @@ trait UserActions
      * Writes the account information to disk
      *
      * @param array $credentials
-     * @return boolean
+     * @return bool
      */
     protected function writeCredentials(array $credentials): bool
     {

kirby/src/Cms/UserPicker.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Kirby\Cms;
+
+use Kirby\Exception\InvalidArgumentException;
+
+/**
+ * The UserPicker class helps to
+ * fetch the right files for the API calls
+ * for the user picker component in the panel.
+ *
+ * @package   Kirby Cms
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://getkirby.com/license
+ */
+class UserPicker extends Picker
+{
+    /**
+     * Extends the basic defaults
+     *
+     * @return array
+     */
+    public function defaults(): array
+    {
+        $defaults = parent::defaults();
+        $defaults['text'] = '{{ user.username }}';
+
+        return $defaults;
+    }
+
+    /**
+     * Search all users for the picker
+     *
+     * @return \Kirby\Cms\Users|null
+     */
+    public function items()
+    {
+        $model = $this->options['model'];
+
+        // find the right default query
+        if (empty($this->options['query']) === false) {
+            $query = $this->options['query'];
+        } elseif (is_a($model, 'Kirby\Cms\User') === true) {
+            $query = 'user.siblings';
+        } else {
+            $query = 'kirby.users';
+        }
+
+        // fetch all users for the picker
+        $users = $model->query($query);
+
+        // catch invalid data
+        if (is_a($users, 'Kirby\Cms\Users') === false) {
+            throw new InvalidArgumentException('Your query must return a set of users');
+        }
+
+        // search
+        $users = $this->search($users);
+
+        // sort
+        $users = $users->sortBy('username', 'asc');
+
+        // paginate
+        return $this->paginate($users);
+    }
+}

kirby/src/Data/Data.php

@@ -50,7 +50,7 @@ class Data
     /**
      * Handler getter
      *
-     * @param  string  $type
+     * @param string $type
      * @return \Kirby\Data\Handler
      */
     public static function handler(string $type)
@@ -73,8 +73,8 @@ class Data
     /**
      * Decodes data with the specified handler
      *
-     * @param  string $data
-     * @param  string $type
+     * @param string $data
+     * @param string $type
      * @return array
      */
     public static function decode(string $data = null, string $type): array
@@ -85,8 +85,8 @@ class Data
     /**
      * Encodes data with the specified handler
      *
-     * @param  array  $data
-     * @param  string $type
+     * @param array $data
+     * @param string $type
      * @return string
      */
     public static function encode(array $data = null, string $type): string
@@ -99,8 +99,8 @@ class Data
      * the data handler is automatically chosen by
      * the extension if not specified
      *
-     * @param  string $file
-     * @param  string $type
+     * @param string $file
+     * @param string $type
      * @return array
      */
     public static function read(string $file, string $type = null): array
@@ -113,10 +113,10 @@ class Data
      * the data handler is automatically chosen by
      * the extension if not specified
      *
-     * @param  string  $file
-     * @param  array   $data
-     * @param  string  $type
-     * @return boolean
+     * @param string $file
+     * @param array $data
+     * @param string $type
+     * @return bool
      */
     public static function write(string $file = null, array $data = [], string $type = null): bool
     {

kirby/src/Data/Handler.php

@@ -23,7 +23,7 @@ abstract class Handler
      *
      * Needs to throw an Exception if the file can't be parsed.
      *
-     * @param  string $string
+     * @param string $string
      * @return array
      */
     abstract public static function decode($string): array;
@@ -31,7 +31,7 @@ abstract class Handler
     /**
      * Converts an array to an encoded string
      *
-     * @param  mixed  $data
+     * @param mixed $data
      * @return string
      */
     abstract public static function encode($data): string;
@@ -39,7 +39,7 @@ abstract class Handler
     /**
      * Reads data from a file
      *
-     * @param  string $file
+     * @param string $file
      * @return array
      */
     public static function read(string $file): array
@@ -54,9 +54,9 @@ abstract class Handler
     /**
      * Writes data to a file
      *
-     * @param  string  $file
-     * @param  array   $data
-     * @return boolean
+     * @param string $file
+     * @param array $data
+     * @return bool
      */
     public static function write(string $file = null, array $data = []): bool
     {

kirby/src/Data/Json.php

@@ -18,7 +18,7 @@ class Json extends Handler
     /**
      * Converts an array to an encoded JSON string
      *
-     * @param  mixed  $data
+     * @param mixed $data
      * @return string
      */
     public static function encode($data): string

kirby/src/Data/PHP.php

@@ -19,8 +19,8 @@ class PHP extends Handler
     /**
      * Converts an array to PHP file content
      *
-     * @param  mixed  $data
-     * @param  string $indent For internal use only
+     * @param mixed $data
+     * @param string $indent For internal use only
      * @return string
      */
     public static function encode($data, $indent = ''): string
@@ -48,7 +48,7 @@ class PHP extends Handler
     /**
      * PHP arrays don't have to be decoded
      *
-     * @param  array $array
+     * @param array $array
      * @return array
      */
     public static function decode($array): array
@@ -59,7 +59,7 @@ class PHP extends Handler
     /**
      * Reads data from a file
      *
-     * @param  string $file
+     * @param string $file
      * @return array
      */
     public static function read(string $file): array
@@ -74,9 +74,9 @@ class PHP extends Handler
     /**
      * Creates a PHP file with the given data
      *
-     * @param  string  $file
-     * @param  array   $data
-     * @return boolean
+     * @param string $file
+     * @param array $data
+     * @return bool
      */
     public static function write(string $file = null, array $data = []): bool
     {

kirby/src/Data/Txt.php

@@ -18,7 +18,7 @@ class Txt extends Handler
     /**
      * Converts an array to an encoded Kirby txt string
      *
-     * @param  mixed  $data
+     * @param mixed $data
      * @return string
      */
     public static function encode($data): string
@@ -41,7 +41,7 @@ class Txt extends Handler
     /**
      * Helper for converting the value
      *
-     * @param  array|string $value
+     * @param array|string $value
      * @return string
      */
     protected static function encodeValue($value): string
@@ -63,8 +63,8 @@ class Txt extends Handler
     /**
      * Helper for converting the key and value to the result string
      *
-     * @param  string $key
-     * @param  string $value
+     * @param string $key
+     * @param string $value
      * @return string
      */
     protected static function encodeResult(string $key, string $value): string
@@ -86,7 +86,7 @@ class Txt extends Handler
     /**
      * Parses a Kirby txt string and returns a multi-dimensional array
      *
-     * @param  string $string
+     * @param string $string
      * @return array
      */
     public static function decode($string): array

kirby/src/Data/Yaml.php

@@ -19,7 +19,7 @@ class Yaml extends Handler
     /**
      * Converts an array to an encoded YAML string
      *
-     * @param  mixed  $data
+     * @param mixed $data
      * @return string
      */
     public static function encode($data): string
@@ -42,7 +42,7 @@ class Yaml extends Handler
     /**
      * Parses an encoded YAML string and returns a multi-dimensional array
      *
-     * @param  string $yaml
+     * @param string $yaml
      * @return array
      */
     public static function decode($yaml): array

kirby/src/Database/Database.php

@@ -64,7 +64,7 @@ class Database
     /**
      * Set to true to throw exceptions on failed queries
      *
-     * @var boolean
+     * @var bool
      */
     protected $fail = false;
 
@@ -232,7 +232,7 @@ class Database
     /**
      * Sets the exception mode for the next query
      *
-     * @param boolean $fail
+     * @param bool $fail
      * @return \Kirby\Database\Database
      */
     public function fail(bool $fail = true)
@@ -358,7 +358,7 @@ class Database
      *
      * @param string $query
      * @param array $bindings
-     * @return boolean
+     * @return bool
      */
     protected function hit(string $query, array $bindings = []): bool
     {
@@ -455,7 +455,7 @@ class Database
      *
      * @param string $query
      * @param array $bindings
-     * @return boolean
+     * @return bool
      */
     public function execute(string $query, array $bindings = []): bool
     {
@@ -491,7 +491,7 @@ class Database
      * Checks if a table exists in the current database
      *
      * @param string $table
-     * @return boolean
+     * @return bool
      */
     public function validateTable(string $table): bool
     {
@@ -515,7 +515,7 @@ class Database
      *
      * @param string $table
      * @param string $column
-     * @return boolean
+     * @return bool
      */
     public function validateColumn(string $table, string $column): bool
     {
@@ -544,7 +544,7 @@ class Database
      *
      * @param string $table
      * @param array $columns
-     * @return boolean
+     * @return bool
      */
     public function createTable($table, $columns = []): bool
     {
@@ -566,7 +566,7 @@ class Database
      * Drops a table
      *
      * @param string $table
-     * @return boolean
+     * @return bool
      */
     public function dropTable($table): bool
     {

kirby/src/Database/Query.php

@@ -87,7 +87,7 @@ class Query
     /**
      * Boolean for if exceptions should be thrown on failing queries
      *
-     * @var boolean
+     * @var bool
      */
     protected $fail = false;
 
@@ -129,21 +129,21 @@ class Query
     /**
      * The offset, which should be applied to the select query
      *
-     * @var integer
+     * @var int
      */
     protected $offset = 0;
 
     /**
      * The limit, which should be applied to the select query
      *
-     * @var integer
+     * @var int
      */
     protected $limit;
 
     /**
      * Boolean to enable query debugging
      *
-     * @var boolean
+     * @var bool
      */
     protected $debug = false;
 
@@ -184,7 +184,7 @@ class Query
      * If enabled, the query will return an array with all important info about
      * the query instead of actually executing the query and returning results
      *
-     * @param boolean $debug
+     * @param bool $debug
      * @return \Kirby\Database\Query
      */
     public function debug(bool $debug = true)
@@ -196,7 +196,7 @@ class Query
     /**
      * Enables distinct select clauses.
      *
-     * @param boolean $distinct
+     * @param bool $distinct
      * @return \Kirby\Database\Query
      */
     public function distinct(bool $distinct = true)
@@ -209,7 +209,7 @@ class Query
      * Enables failing queries.
      * If enabled queries will no longer fail silently but throw an exception
      *
-     * @param boolean $fail
+     * @param bool $fail
      * @return \Kirby\Database\Query
      */
     public function fail(bool $fail = true)
@@ -880,7 +880,7 @@ class Query
      *
      * @param array $values You can pass values here or set them with ->values() before
      * @param mixed $where You can pass a where clause here or set it with ->where() before
-     * @return boolean
+     * @return bool
      */
     public function update($values = null, $where = null)
     {
@@ -891,7 +891,7 @@ class Query
      * Fires a delete query
      *
      * @param mixed $where You can pass a where clause here or set it with ->where() before
-     * @return boolean
+     * @return bool
      */
     public function delete($where = null)
     {

kirby/src/Database/Sql.php

@@ -112,7 +112,7 @@ class Sql
      *
      * @param string $table
      * @param string $column
-     * @param boolean $enforceQualified
+     * @param bool $enforceQualified
      * @return string|null
      */
     public function columnName(string $table, string $column, bool $enforceQualified = false): ?string
@@ -483,8 +483,8 @@ class Sql
     /**
      * Creates a limit and offset query instruction
      *
-     * @param integer $offset
-     * @param integer|null $limit
+     * @param int $offset
+     * @param int|null $limit
      * @return array
      */
     public function limit(int $offset = 0, int $limit = null): array
@@ -780,7 +780,7 @@ class Sql
      *
      * @param string $table
      * @param string $column
-     * @return boolean
+     * @return bool
      */
     public function validateColumn(string $table, string $column): bool
     {
@@ -797,8 +797,8 @@ class Sql
      * @param string $table Table name
      * @param mixed $values A value string or array of values
      * @param string $separator A separator which should be used to join values
-     * @param boolean $set If true builds a set list of values for update clauses
-     * @param boolean $enforceQualified Always use fully qualified column names
+     * @param bool $set If true builds a set list of values for update clauses
+     * @param bool $enforceQualified Always use fully qualified column names
      */
     public function values(string $table, $values, string $separator = ', ', bool $set = true, bool $enforceQualified = false): array
     {

kirby/src/Exception/ErrorPageException.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Kirby\Exception;
+
+/**
+ * ErrorPageException
+ * Thrown to trigger the CMS error page
+ *
+ * @package   Kirby Exception
+ * @author    Lukas Bestle <lukas@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://opensource.org/licenses/MIT
+ */
+class ErrorPageException extends Exception
+{
+    protected static $defaultKey = 'errorPage';
+    protected static $defaultFallback = 'Triggered error page';
+    protected static $defaultHttpCode = 404;
+}

kirby/src/Exception/Exception.php

@@ -42,7 +42,7 @@ class Exception extends \Exception
     /**
      * Whether the exception message could be translated into the user's language
      *
-     * @var boolean
+     * @var bool
      */
     protected $isTranslated = true;
 
@@ -194,7 +194,7 @@ class Exception extends \Exception
      * Returns whether the exception message could
      * be translated into the user's language
      *
-     * @return boolean
+     * @return bool
      */
     final public function isTranslated(): bool
     {

kirby/src/Form/Field.php

@@ -203,6 +203,13 @@ class Field extends Component
 
                     return $this->model()->toString($this->default);
                 },
+                'help' => function () {
+                    if ($this->help) {
+                        $help = $this->model()->toString($this->help);
+                        $help = $this->kirby()->kirbytext($help);
+                        return $help;
+                    }
+                },
                 'label' => function () {
                     if ($this->label !== null) {
                         return $this->model()->toString($this->label);

kirby/src/Form/Form.php

@@ -61,14 +61,7 @@ class Form
             try {
                 $field = new Field($props['type'], $props);
             } catch (Throwable $e) {
-                $props = array_merge($props, [
-                    'name'  => $props['name'],
-                    'label' => 'Error in "' . $props['name'] . '" field',
-                    'theme' => 'negative',
-                    'text'  => $e->getMessage(),
-                ]);
-
-                $field = new Field('info', $props);
+                $field = static::exceptionField($e, $props);
             }
 
             if ($field->save() !== false) {
@@ -127,6 +120,17 @@ class Form
         return $this->errors;
     }
 
+    public static function exceptionField(Throwable $exception, array $props = [])
+    {
+        $props = array_merge($props, [
+            'label' => 'Error in "' . $props['name'] . '" field',
+            'theme' => 'negative',
+            'text'  => strip_tags($exception->getMessage()),
+        ]);
+
+        return new Field('info', $props);
+    }
+
     public function fields()
     {
         return $this->fields;

kirby/src/Http/Cookie.php

@@ -32,12 +32,12 @@ class Cookie
      *
      * </code>
      *
-     * @param  string  $key       The name of the cookie
-     * @param  string  $value     The cookie content
-     * @param  array   $options   Array of options:
-     *                            lifetime, path, domain, secure, httpOnly
-     * @return boolean            true: cookie was created,
-     *                            false: cookie creation failed
+     * @param string $key The name of the cookie
+     * @param string $value The cookie content
+     * @param array $options Array of options:
+     *                       lifetime, path, domain, secure, httpOnly
+     * @return bool true: cookie was created,
+     *              false: cookie creation failed
      */
     public static function set(string $key, string $value, array $options = []): bool
     {
@@ -61,7 +61,7 @@ class Cookie
     /**
      * Calculates the lifetime for a cookie
      *
-     * @param  int $minutes Number of minutes or timestamp
+     * @param int $minutes Number of minutes or timestamp
      * @return int
      */
     public static function lifetime(int $minutes): int
@@ -87,12 +87,12 @@ class Cookie
      *
      * </code>
      *
-     * @param  string  $key       The name of the cookie
-     * @param  string  $value     The cookie content
-     * @param  array   $options   Array of options:
-     *                            path, domain, secure, httpOnly
-     * @return boolean            true: cookie was created,
-     *                            false: cookie creation failed
+     * @param string $key The name of the cookie
+     * @param string $value The cookie content
+     * @param array $options Array of options:
+     *                       path, domain, secure, httpOnly
+     * @return bool true: cookie was created,
+     *              false: cookie creation failed
      */
     public static function forever(string $key, string $value, array $options = []): bool
     {
@@ -110,10 +110,10 @@ class Cookie
      *
      * </code>
      *
-     * @param  string|null  $key     The name of the cookie
-     * @param  string|null  $default The default value, which should be returned
-     *                               if the cookie has not been found
-     * @return mixed                 The found value
+     * @param string|null $key The name of the cookie
+     * @param string|null $default The default value, which should be returned
+     *                             if the cookie has not been found
+     * @return mixed The found value
      */
     public static function get(string $key = null, string $default = null)
     {
@@ -127,8 +127,8 @@ class Cookie
     /**
      * Checks if a cookie exists
      *
-     * @param  string  $key
-     * @return boolean
+     * @param string $key
+     * @return bool
      */
     public static function exists(string $key): bool
     {
@@ -139,7 +139,7 @@ class Cookie
      * Creates a HMAC for the cookie value
      * Used as a cookie signature to prevent easy tampering with cookie data
      *
-     * @param  string $value
+     * @param string $value
      * @return string
      */
     protected static function hmac(string $value): string
@@ -151,7 +151,7 @@ class Cookie
      * Parses the hashed value from a cookie
      * and tries to extract the value
      *
-     * @param  string $string
+     * @param string $string
      * @return mixed
      */
     protected static function parse(string $string)
@@ -190,9 +190,9 @@ class Cookie
      *
      * </code>
      *
-     * @param  string  $key The name of the cookie
-     * @return boolean      true: the cookie has been removed,
-     *                      false: the cookie could not be removed
+     * @param string $key The name of the cookie
+     * @return bool true: the cookie has been removed,
+     *              false: the cookie could not be removed
      */
     public static function remove(string $key): bool
     {

kirby/src/Http/Header.php

@@ -58,7 +58,7 @@ class Header
      *
      * @param string $mime
      * @param string $charset
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function contentType(string $mime, string $charset = 'UTF-8', bool $send = true)
@@ -108,7 +108,7 @@ class Header
      *
      * @param string $mime
      * @param string $charset
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function type(string $mime, string $charset = 'UTF-8', bool $send = true)
@@ -124,7 +124,7 @@ class Header
      * as 3 digits followed by a space and a message, e.g. '999 Custom Status'.
      *
      * @param int|string $code The HTTP status code
-     * @param boolean $send If set to false the header will be returned instead
+     * @param bool $send If set to false the header will be returned instead
      * @return string|void
      */
     public static function status($code = null, bool $send = true)
@@ -154,7 +154,7 @@ class Header
     /**
      * Sends a 200 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function success(bool $send = true)
@@ -165,7 +165,7 @@ class Header
     /**
      * Sends a 201 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function created(bool $send = true)
@@ -176,7 +176,7 @@ class Header
     /**
      * Sends a 202 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function accepted(bool $send = true)
@@ -187,7 +187,7 @@ class Header
     /**
      * Sends a 400 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function error(bool $send = true)
@@ -198,7 +198,7 @@ class Header
     /**
      * Sends a 403 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function forbidden(bool $send = true)
@@ -209,7 +209,7 @@ class Header
     /**
      * Sends a 404 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function notfound(bool $send = true)
@@ -220,7 +220,7 @@ class Header
     /**
      * Sends a 404 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function missing(bool $send = true)
@@ -231,7 +231,7 @@ class Header
     /**
      * Sends a 410 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function gone(bool $send = true)
@@ -242,7 +242,7 @@ class Header
     /**
      * Sends a 500 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function panic(bool $send = true)
@@ -253,7 +253,7 @@ class Header
     /**
      * Sends a 503 header
      *
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function unavailable(bool $send = true)
@@ -266,7 +266,7 @@ class Header
      *
      * @param string $url
      * @param int $code
-     * @param boolean $send
+     * @param bool $send
      * @return string|void
      */
     public static function redirect(string $url, int $code = 302, bool $send = true)

kirby/src/Http/Params.php

@@ -116,8 +116,8 @@ class Params extends Query
      * Converts the params object to a params string
      * which can then be used in the URL builder again
      *
-     * @param boolean $leadingSlash
-     * @param boolean $trailingSlash
+     * @param bool $leadingSlash
+     * @param bool $trailingSlash
      * @return string|null
      */
     public function toString($leadingSlash = false, $trailingSlash = false): string

kirby/src/Http/Remote.php

@@ -113,7 +113,7 @@ class Remote
     /**
      * Returns the http status code
      *
-     * @return integer|null
+     * @return int|null
      */
     public function code(): ?int
     {

kirby/src/Http/Request.php

@@ -142,16 +142,6 @@ class Request
         ];
     }
 
-    /**
-     * Detects ajax requests
-     * @deprecated 3.1.0 No longer reliable, especially with the fetch api.
-     * @return boolean
-     */
-    public function ajax(): bool
-    {
-        return isset($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) === 'xmlhttprequest';
-    }
-
     /**
      * Returns the Auth object if authentication is set
      *
@@ -191,7 +181,7 @@ class Request
     /**
      * Checks if the request has been made from the command line
      *
-     * @return boolean
+     * @return bool
      */
     public function cli(): bool
     {
@@ -232,7 +222,7 @@ class Request
      * Fetches a single file array
      * from the Files object by key
      *
-     * @param  string $key
+     * @param string $key
      * @return array|null
      */
     public function file(string $key)
@@ -316,8 +306,8 @@ class Request
      * Checks if the given method name
      * matches the name of the request method.
      *
-     * @param  string  $method
-     * @return boolean
+     * @param string $method
+     * @return bool
      */
     public function is(string $method): bool
     {
@@ -363,7 +353,7 @@ class Request
     /**
      * Checks for a valid SSL connection
      *
-     * @return boolean
+     * @return bool
      */
     public function ssl(): bool
     {

kirby/src/Http/Request/Data.php

@@ -44,8 +44,8 @@ trait Data
      * of the data array by key or multiple values by
      * passing an array of keys.
      *
-     * @param  string|array $key
-     * @param  mixed|null   $default
+     * @param string|array $key
+     * @param mixed|null $default
      * @return mixed
      */
     public function get($key, $default = null)

kirby/src/Http/Response.php

@@ -58,11 +58,11 @@ class Response
     /**
      * Creates a new response object
      *
-     * @param string  $body
-     * @param string  $type
-     * @param integer $code
-     * @param array   $headers
-     * @param string  $charset
+     * @param string $body
+     * @param string $type
+     * @param int $code
+     * @param array $headers
+     * @param string $charset
      */
     public function __construct($body = '', ?string $type = null, ?int $code = null, ?array $headers = null, ?string $charset = null)
     {
@@ -194,7 +194,7 @@ class Response
     /**
      * Getter for single headers
      *
-     * @param  string      $key   Name of the header
+     * @param string $key Name of the header
      * @return string|null
      */
     public function header(string $key): ?string
@@ -217,8 +217,8 @@ class Response
      * header and automatic conversion of arrays.
      *
      * @param string|array $body
-     * @param integer $code
-     * @param boolean $pretty
+     * @param int $code
+     * @param bool $pretty
      * @param array $headers
      * @return self
      */
@@ -242,7 +242,7 @@ class Response
      * given location.
      *
      * @param string $location
-     * @param integer $code
+     * @param int $code
      * @return self
      */
     public static function redirect(?string $location = null, ?int $code = null)

kirby/src/Http/Route.php

@@ -90,7 +90,7 @@ class Route
      *
      * @param string|array $pattern
      * @param string|array $method
-     * @param Closure      $action
+     * @param Closure $action
      * @param array $attributes
      */
     public function __construct($pattern, $method = 'GET', Closure $action, array $attributes = [])
@@ -177,7 +177,7 @@ class Route
      * Converts the pattern into a full regular
      * expression by replacing all the wildcards
      *
-     * @param  string $pattern
+     * @param string $pattern
      * @return string
      */
     public function regex(string $pattern): string
@@ -201,8 +201,8 @@ class Route
      * Tries to match the path with the regular expression and
      * extracts all arguments for the Route action
      *
-     * @param  string       $pattern
-     * @param  string       $path
+     * @param string $pattern
+     * @param string $path
      * @return array|false
      */
     public function parse(string $pattern, string $path)

kirby/src/Http/Router.php

@@ -81,9 +81,9 @@ class Router
      * the appropriate arguments and a Result
      * object.
      *
-     * @param  string $path
-     * @param  string $method
-     * @param  Closure|null $callback
+     * @param string $path
+     * @param string $method
+     * @param Closure|null $callback
      * @return mixed
      */
     public function call(string $path = null, string $method = 'GET', Closure $callback = null)
@@ -126,9 +126,9 @@ class Router
      * find matches and return all the found
      * arguments in the path.
      *
-     * @param  string $path
-     * @param  string $method
-     * @param  array  $ignore
+     * @param string $path
+     * @param string $method
+     * @param array $ignore
      * @return \Kirby\Http\Route|null
      */
     public function find(string $path, string $method, array $ignore = null)

kirby/src/Http/Server.php

@@ -34,7 +34,7 @@ class Server
     /**
      * Checks if the request is being served by the CLI
      *
-     * @return boolean
+     * @return bool
      */
     public static function cli(): bool
     {
@@ -66,10 +66,10 @@ class Server
      * // returns the whole server array
      * </code>
      *
-     * @param  mixed    $key     The key to look for. Pass false or null to
-     *                           return the entire server array.
-     * @param  mixed    $default Optional default value, which should be
-     *                           returned if no element has been found
+     * @param mixed $key The key to look for. Pass false or null to
+     *                   return the entire server array.
+     * @param mixed $default Optional default value, which should be
+     *                       returned if no element has been found
      * @return mixed
      */
     public static function get($key = null, $default = null)
@@ -86,8 +86,8 @@ class Server
     /**
      * Help to sanitize some _SERVER keys
      *
-     * @param  string $key
-     * @param  mixed $value
+     * @param string $key
+     * @param mixed $value
      * @return mixed
      */
     public static function sanitize(string $key, $value)
@@ -131,7 +131,7 @@ class Server
     /**
      * Checks for a https request
      *
-     * @return boolean
+     * @return bool
      */
     public static function https(): bool
     {

kirby/src/Http/Uri.php

@@ -90,7 +90,7 @@ class Uri
     protected $scheme = 'http';
 
     /**
-     * @var boolean
+     * @var bool
      */
     protected $slash = false;
 
@@ -237,7 +237,7 @@ class Uri
 
     /**
      * @param array $props
-     * @param boolean $forwarded
+     * @param bool $forwarded
      * @return self
      */
     public static function current(array $props = [], bool $forwarded = false)
@@ -289,7 +289,7 @@ class Uri
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public function hasFragment(): bool
     {
@@ -297,7 +297,7 @@ class Uri
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public function hasPath(): bool
     {
@@ -305,7 +305,7 @@ class Uri
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public function hasQuery(): bool
     {
@@ -373,7 +373,7 @@ class Uri
     }
 
     /**
-     * @param  string|null $fragment
+     * @param string|null $fragment
      * @return self
      */
     public function setFragment(string $fragment = null)
@@ -383,7 +383,7 @@ class Uri
     }
 
     /**
-     * @param  string $host
+     * @param string $host
      * @return self
      */
     public function setHost(string $host = null)
@@ -393,7 +393,7 @@ class Uri
     }
 
     /**
-     * @param  Kirby\Http\Params|string|array|null $params
+     * @param \Kirby\Http\Params|string|array|null $params
      * @return self
      */
     public function setParams($params = null)
@@ -403,7 +403,7 @@ class Uri
     }
 
     /**
-     * @param  string|null $password
+     * @param string|null $password
      * @return self
      */
     public function setPassword(string $password = null)
@@ -453,7 +453,7 @@ class Uri
     }
 
     /**
-     * @param  string $scheme
+     * @param string $scheme
      * @return self
      */
     public function setScheme(string $scheme = null)
@@ -480,7 +480,7 @@ class Uri
     }
 
     /**
-     * @param  string|null $username
+     * @param string|null $username
      * @return self
      */
     public function setUsername(string $username = null)

kirby/src/Http/Url.php

@@ -112,7 +112,7 @@ class Url
      * Checks if an URL is absolute
      *
      * @param string $url
-     * @return boolean
+     * @return bool
      */
     public static function isAbsolute(string $url = null): bool
     {
@@ -194,7 +194,7 @@ class Url
      *
      * @param string $url
      * @param int $length
-     * @param boolean $base
+     * @param bool $base
      * @param string $rep
      * @return string
      */

kirby/src/Http/Visitor.php

@@ -66,7 +66,7 @@ class Visitor
      * provided or returns the user's
      * accepted language otherwise
      *
-     * @param  string|null $acceptedLanguage
+     * @param string|null $acceptedLanguage
      * @return \Kirby\Toolkit\Obj|\Kirby\Http\Visitor|null
      */
     public function acceptedLanguage(string $acceptedLanguage = null)
@@ -133,7 +133,7 @@ class Visitor
      * provided or returns the user's
      * accepted mime type otherwise
      *
-     * @param  string|null $acceptedMimeType
+     * @param string|null $acceptedMimeType
      * @return \Kirby\Toolkit\Obj|\Kirby\Http\Visitor
      */
     public function acceptedMimeType(string $acceptedMimeType = null)
@@ -169,20 +169,57 @@ class Visitor
     /**
      * Checks if the user accepts the given mime type
      *
-     * @param  string $mimeType
-     * @return boolean
+     * @param string $mimeType
+     * @return bool
      */
     public function acceptsMimeType(string $mimeType): bool
     {
         return Mime::isAccepted($mimeType, $this->acceptedMimeType);
     }
 
+    /**
+     * Returns the MIME type from the provided list that
+     * is most accepted (= preferred) by the visitor
+     *
+     * @param string ...$mimeTypes MIME types to query for
+     * @return string|null Preferred MIME type
+     */
+    public function preferredMimeType(string ...$mimeTypes): ?string
+    {
+        foreach ($this->acceptedMimeTypes() as $acceptedMime) {
+            // look for direct matches
+            if (in_array($acceptedMime->type(), $mimeTypes)) {
+                return $acceptedMime->type();
+            }
+
+            // test each option against wildcard `Accept` values
+            foreach ($mimeTypes as $expectedMime) {
+                if (Mime::matches($expectedMime, $acceptedMime->type()) === true) {
+                    return $expectedMime;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns true if the visitor prefers a JSON response over
+     * an HTML response based on the `Accept` request header
+     *
+     * @return bool
+     */
+    public function prefersJson(): bool
+    {
+        return $this->preferredMimeType('application/json', 'text/html') === 'application/json';
+    }
+
     /**
      * Sets the ip address if provided
      * or returns the ip of the current
      * visitor otherwise
      *
-     * @param  string|null $ip
+     * @param string|null $ip
      * @return string|Visitor|null
      */
     public function ip(string $ip = null)
@@ -199,7 +236,7 @@ class Visitor
      * or returns the user agent string of
      * the current visitor otherwise
      *
-     * @param  string|null $userAgent
+     * @param string|null $userAgent
      * @return string|Visitor|null
      */
     public function userAgent(string $userAgent = null)

kirby/src/Image/Dimensions.php

@@ -65,9 +65,9 @@ class Dimensions
     /**
      * Crops the dimensions by width and height
      *
-     * @param    int         $width
-     * @param    int         $height
-     * @return   self
+     * @param int $width
+     * @param int $height
+     * @return self
      */
     public function crop(int $width, int $height = null)
     {
@@ -107,9 +107,9 @@ class Dimensions
      *
      * </code>
      *
-     * @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
+     * @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
      */
     public function fit(int $box, bool $force = false)
@@ -159,10 +159,10 @@ class Dimensions
      *
      * </code>
      *
-     * @param   int         $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
+     * @param int $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
      */
     public function fitHeight(int $fit = null, bool $force = false)
     {
@@ -172,11 +172,11 @@ class Dimensions
     /**
      * Helper for fitWidth and fitHeight methods
      *
-     * @param   string      $ref    reference (width or height)
-     * @param   int         $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
+     * @param string $ref reference (width or height)
+     * @param int $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
      */
     protected function fitSize(string $ref, int $fit = null, bool $force = false)
     {
@@ -212,10 +212,10 @@ class Dimensions
      *
      * </code>
      *
-     * @param   int         $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
+     * @param int $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
      */
     public function fitWidth(int $fit = null, bool $force = false)
     {
@@ -225,10 +225,10 @@ class Dimensions
     /**
      * Recalculates the dimensions by the width and height
      *
-     * @param   int         $width      the max height
-     * @param   int         $height     the max width
-     * @param   bool        $force
-     * @return  self
+     * @param int $width the max height
+     * @param int $height the max width
+     * @param bool $force
+     * @return self
      */
     public function fitWidthAndHeight(int $width = null, int $height = null, bool $force = false)
     {
@@ -362,10 +362,10 @@ class Dimensions
     }
 
     /**
-     * @param   int         $width
-     * @param   int         $height
-     * @param   bool        $force
-     * @return  self
+     * @param int $width
+     * @param int $height
+     * @param bool $force
+     * @return self
      */
     public function resize(int $width = null, int $height = null, bool $force = false)
     {
@@ -385,7 +385,7 @@ class Dimensions
     /**
      * Resize and crop
      *
-     * @param  array $options
+     * @param array $options
      * @return self
      */
     public function thumb(array $options = [])

kirby/src/Image/Exif.php

@@ -173,7 +173,7 @@ class Exif
     /**
      * Checks if this is a color picture
      *
-     * @return boolean|null
+     * @return bool|null
      */
     public function isColor()
     {
@@ -183,7 +183,7 @@ class Exif
     /**
      * Checks if this is a bw picture
      *
-     * @return boolean|null
+     * @return bool|null
      */
     public function isBW(): bool
     {

kirby/src/Image/Image.php

@@ -42,8 +42,8 @@ class Image extends File
     /**
      * Constructor
      *
-     * @param string       $root
-     * @param string|null  $url
+     * @param string $root
+     * @param string|null $url
      */
     public function __construct(string $root = null, string $url = null)
     {
@@ -126,7 +126,7 @@ class Image extends File
     /**
      * Sends an appropriate header for the asset
      *
-     * @param  boolean          $send
+     * @param bool $send
      * @return \Kirby\Http\Response|string
      */
     public function header(bool $send = true)
@@ -147,7 +147,7 @@ class Image extends File
     }
 
     /**
-     * @param  array  $attr
+     * @param array $attr
      * @return string
      */
     public function html(array $attr = []): string
@@ -168,7 +168,7 @@ class Image extends File
     /**
      * Checks if the dimensions of the asset are portrait
      *
-     * @return boolean
+     * @return bool
      */
     public function isPortrait(): bool
     {
@@ -178,7 +178,7 @@ class Image extends File
     /**
      * Checks if the dimensions of the asset are landscape
      *
-     * @return boolean
+     * @return bool
      */
     public function isLandscape(): bool
     {
@@ -188,7 +188,7 @@ class Image extends File
     /**
      * Checks if the dimensions of the asset are square
      *
-     * @return boolean
+     * @return bool
      */
     public function isSquare(): bool
     {

kirby/src/Image/Location.php

@@ -68,8 +68,8 @@ class Location
     /**
      * Converts the gps coordinates
      *
-     * @param  string|array $coord
-     * @param  string       $hemi
+     * @param string|array $coord
+     * @param string $hemi
      * @return float
      */
     protected function gps($coord, string $hemi): float
@@ -87,7 +87,7 @@ class Location
     /**
      * Converts coordinates to floats
      *
-     * @param  string $part
+     * @param string $part
      * @return float
      */
     protected function num(string $part): float

kirby/src/Session/AutoSession.php

@@ -21,19 +21,13 @@ class AutoSession
     /**
      * Creates a new AutoSession instance
      *
-     * @param \Kirby\Session\SessionStore|string $store   SessionStore object or a path to the storage directory (uses the FileSessionStore)
-     * @param array               $options Optional additional options:
-     *                                     - `durationNormal`: Duration of normal sessions in seconds
-     *                                                         Defaults to 2 hours
-     *                                     - `durationLong`:   Duration of "remember me" sessions in seconds
-     *                                                         Defaults to 2 weeks
-     *                                     - `timeout`:        Activity timeout in seconds (integer or false for none)
-     *                                                         *Only* used for normal sessions
-     *                                                         Defaults to `1800` (half an hour)
-     *                                     - `cookieName`:     Name to use for the session cookie
-     *                                                         Defaults to `kirby_session`
-     *                                     - `gcInterval`:     How often should the garbage collector be run?
-     *                                                         Integer or `false` for never; defaults to `100`
+     * @param \Kirby\Session\SessionStore|string $store SessionStore object or a path to the storage directory (uses the FileSessionStore)
+     * @param array $options Optional additional options:
+     *                       - `durationNormal`: Duration of normal sessions in seconds; defaults to 2 hours
+     *                       - `durationLong`: Duration of "remember me" sessions in seconds; defaults to 2 weeks
+     *                       - `timeout`: Activity timeout in seconds (integer or false for none); *only* used for normal sessions; defaults to `1800` (half an hour)
+     *                       - `cookieName`: Name to use for the session cookie; defaults to `kirby_session`
+     *                       - `gcInterval`: How often should the garbage collector be run?; integer or `false` for never; defaults to `100`
      */
     public function __construct($store, array $options = [])
     {
@@ -56,15 +50,10 @@ class AutoSession
     /**
      * Returns the automatic session
      *
-     * @param  array   $options Optional additional options:
-     *                          - `detect`:     Whether to allow sessions in the `Authorization` HTTP header (`true`)
-     *                                          or only in the session cookie (`false`)
-     *                                          Defaults to `false`
-     *                          - `createMode`: When creating a new session, should it be set as a cookie or is it going
-     *                                          to be transmitted manually to be used in a header?
-     *                                          Defaults to `cookie`
-     *                          - `long`:       Whether the session is a long "remember me" session or a normal session
-     *                                          Defaults to `false`
+     * @param array $options Optional additional options:
+     *                       - `detect`: Whether to allow sessions in the `Authorization` HTTP header (`true`) or only in the session cookie (`false`); defaults to `false`
+     *                       - `createMode`: When creating a new session, should it be set as a cookie or is it going to be transmitted manually to be used in a header?; defaults to `cookie`
+     *                       - `long`: Whether the session is a long "remember me" session or a normal session; defaults to `false`
      * @return \Kirby\Session\Session
      */
     public function get(array $options = [])
@@ -139,15 +128,11 @@ class AutoSession
      * Useful for custom applications like a password reset link
      * Does *not* affect the automatic session
      *
-     * @param  array   $options Optional additional options:
-     *                          - `startTime`:  Time the session starts being valid (date string or timestamp)
-     *                                          Defaults to `now`
-     *                          - `expiryTime`: Time the session expires (date string or timestamp)
-     *                                          Defaults to `+ 2 hours`
-     *                          - `timeout`:    Activity timeout in seconds (integer or false for none)
-     *                                          Defaults to `1800` (half an hour)
-     *                          - `renewable`:  Should it be possible to extend the expiry date?
-     *                                          Defaults to `true`
+     * @param array $options Optional additional options:
+     *                       - `startTime`: Time the session starts being valid (date string or timestamp); defaults to `now`
+     *                       - `expiryTime`: Time the session expires (date string or timestamp); defaults to `+ 2 hours`
+     *                       - `timeout`: Activity timeout in seconds (integer or false for none); defaults to `1800` (half an hour)
+     *                       - `renewable`: Should it be possible to extend the expiry date?; defaults to `true`
      * @return \Kirby\Session\Session
      */
     public function createManually(array $options = [])

kirby/src/Session/FileSessionStore.php

@@ -55,8 +55,8 @@ class FileSessionStore extends SessionStore
      * Needs to make sure that the session does not already exist
      * and needs to reserve it by locking it exclusively.
      *
-     * @param  int    $expiryTime Timestamp
-     * @return string             Randomly generated session ID (without timestamp)
+     * @param int $expiryTime Timestamp
+     * @return string Randomly generated session ID (without timestamp)
      */
     public function createId(int $expiryTime): string
     {
@@ -89,10 +89,10 @@ class FileSessionStore extends SessionStore
     /**
      * Checks if the given session exists
      *
-     * @param  int     $expiryTime Timestamp
-     * @param  string  $id         Session ID
-     * @return boolean             true:  session exists,
-     *                             false: session doesn't exist
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
+     * @return bool true:  session exists,
+     *              false: session doesn't exist
      */
     public function exists(int $expiryTime, string $id): bool
     {
@@ -108,8 +108,8 @@ class FileSessionStore extends SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     public function lock(int $expiryTime, string $id)
@@ -146,8 +146,8 @@ class FileSessionStore extends SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     public function unlock(int $expiryTime, string $id)
@@ -187,8 +187,8 @@ class FileSessionStore extends SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return string
      */
     public function get(int $expiryTime, string $id): string
@@ -250,9 +250,9 @@ class FileSessionStore extends SessionStore
      * Needs to make sure that the session exists.
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
-     * @param  string $data       Session data to write
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
+     * @param string $data Session data to write
      * @return void
      */
     public function set(int $expiryTime, string $id, string $data)
@@ -303,8 +303,8 @@ class FileSessionStore extends SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     public function destroy(int $expiryTime, string $id)
@@ -392,8 +392,8 @@ class FileSessionStore extends SessionStore
     /**
      * Returns the combined name based on expiry time and ID
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return string
      */
     protected function name(int $expiryTime, string $id): string
@@ -404,7 +404,7 @@ class FileSessionStore extends SessionStore
     /**
      * Returns the full path to the session file
      *
-     * @param  string $name Combined name
+     * @param string $name Combined name
      * @return string
      */
     protected function path(string $name): string
@@ -415,8 +415,8 @@ class FileSessionStore extends SessionStore
     /**
      * Returns a PHP file handle for a session
      *
-     * @param  string   $name Combined name
-     * @return resource       File handle
+     * @param string $name Combined name
+     * @return resource File handle
      */
     protected function handle(string $name)
     {
@@ -457,7 +457,7 @@ class FileSessionStore extends SessionStore
     /**
      * Closes an open file handle
      *
-     * @param  string $name Combined name
+     * @param string $name Combined name
      * @return void
      */
     protected function closeHandle(string $name)

kirby/src/Session/Session.php

@@ -49,19 +49,14 @@ class Session
     /**
      * Creates a new Session instance
      *
-     * @param \Kirby\Session\Sessions    $sessions Parent sessions object
-     * @param string|null $token    Session token or null for a new session
-     * @param array       $options  Optional additional options:
-     *                              - `mode`:       Token transmission mode (cookie or manual)
-     *                                              Defaults to `cookie`
-     *                              - `startTime`:  Time the session starts being valid (date string or timestamp)
-     *                                              Defaults to `now`
-     *                              - `expiryTime`: Time the session expires (date string or timestamp)
-     *                                              Defaults to `+ 2 hours`
-     *                              - `timeout`:    Activity timeout in seconds (integer or false for none)
-     *                                              Defaults to `1800` (half an hour)
-     *                              - `renewable`:  Should it be possible to extend the expiry date?
-     *                                              Defaults to `true`
+     * @param \Kirby\Session\Sessions $sessions Parent sessions object
+     * @param string|null $token Session token or null for a new session
+     * @param array $options Optional additional options:
+     *                       - `mode`: Token transmission mode (cookie or manual); defaults to `cookie`
+     *                       - `startTime`: Time the session starts being valid (date string or timestamp); defaults to `now`
+     *                       - `expiryTime`: Time the session expires (date string or timestamp); defaults to `+ 2 hours`
+     *                       - `timeout`: Activity timeout in seconds (integer or false for none); defaults to `1800` (half an hour)
+     *                       - `renewable`: Should it be possible to extend the expiry date?; defaults to `true`
      */
     public function __construct(Sessions $sessions, $token, array $options)
     {
@@ -156,8 +151,8 @@ class Session
      * Gets or sets the transmission mode
      * Setting only works for new sessions that haven't been transmitted yet
      *
-     * @param  string $mode Optional new transmission mode
-     * @return string       Transmission mode
+     * @param string $mode Optional new transmission mode
+     * @return string Transmission mode
      */
     public function mode(string $mode = null)
     {
@@ -180,7 +175,7 @@ class Session
     /**
      * Gets the session start time
      *
-     * @return integer Timestamp
+     * @return int Timestamp
      */
     public function startTime(): int
     {
@@ -191,8 +186,8 @@ class Session
      * Gets or sets the session expiry time
      * Setting the expiry time also updates the duration and regenerates the session token
      *
-     * @param  string|integer $expiryTime Optional new expiry timestamp or time string to set
-     * @return integer                    Timestamp
+     * @param string|int $expiryTime Optional new expiry timestamp or time string to set
+     * @return int Timestamp
      */
     public function expiryTime($expiryTime = null): int
     {
@@ -226,8 +221,8 @@ class Session
      * Gets or sets the session duration
      * Setting the duration also updates the expiry time and regenerates the session token
      *
-     * @param  integer $duration Optional new duration in seconds to set
-     * @return integer           Number of seconds
+     * @param int $duration Optional new duration in seconds to set
+     * @return int Number of seconds
      */
     public function duration(int $duration = null): int
     {
@@ -252,8 +247,8 @@ class Session
     /**
      * Gets or sets the session timeout
      *
-     * @param  integer|false $timeout Optional new timeout to set or false to disable timeout
-     * @return integer|false          Number of seconds or false for "no timeout"
+     * @param int|false $timeout Optional new timeout to set or false to disable timeout
+     * @return int|false Number of seconds or false for "no timeout"
      */
     public function timeout($timeout = null)
     {
@@ -288,8 +283,8 @@ class Session
      * Gets or sets the renewable flag
      * Automatically renews the session if renewing gets enabled
      *
-     * @param  boolean $renewable Optional new renewable flag to set
-     * @return boolean
+     * @param bool $renewable Optional new renewable flag to set
+     * @return bool
      */
     public function renewable(bool $renewable = null): bool
     {
@@ -315,8 +310,8 @@ class Session
     /**
      * Magic call method that proxies all calls to session data methods
      *
-     * @param  string $name      Method name (one of set, increment, decrement, get, pull, remove, clear)
-     * @param  array  $arguments Method arguments
+     * @param string $name Method name (one of set, increment, decrement, get, pull, remove, clear)
+     * @param array $arguments Method arguments
      * @return mixed
      */
     public function __call(string $name, array $arguments)
@@ -478,7 +473,7 @@ class Session
      * Returns whether the session token needs to be retransmitted to the client
      * Only relevant in header and manual modes
      *
-     * @return boolean
+     * @return bool
      */
     public function needsRetransmission(): bool
     {
@@ -542,8 +537,8 @@ class Session
     /**
      * Parses a token string into its parts and sets them as instance vars
      *
-     * @param  string $token      Session token
-     * @param  bool   $withoutKey If true, $token is passed without key
+     * @param string $token Session token
+     * @param bool $withoutKey If true, $token is passed without key
      * @return void
      */
     protected function parseToken(string $token, bool $withoutKey = false)
@@ -584,9 +579,9 @@ class Session
     /**
      * Makes sure that the given value is a valid timestamp
      *
-     * @param  string|integer $time Timestamp or date string (must be supported by `strtotime()`)
-     * @param  integer        $now  Timestamp to use as a base for the calculation of relative dates
-     * @return integer              Timestamp value
+     * @param string|int $time Timestamp or date string (must be supported by `strtotime()`)
+     * @param int $now Timestamp to use as a base for the calculation of relative dates
+     * @return int Timestamp value
      */
     protected static function timeToTimestamp($time, int $now = null): int
     {
@@ -762,7 +757,7 @@ class Session
      * Checks if the session can be renewed and if the last renewal
      * was more than half a session duration ago
      *
-     * @return boolean
+     * @return bool
      */
     protected function needsRenewal(): bool
     {

kirby/src/Session/SessionData.php

@@ -37,8 +37,8 @@ class SessionData
     /**
      * Sets one or multiple session values by key
      *
-     * @param  string|array $key   The key to define or a key-value array with multiple values
-     * @param  mixed        $value The value for the passed key (only if one $key is passed)
+     * @param string|array $key The key to define or a key-value array with multiple values
+     * @param mixed $value The value for the passed key (only if one $key is passed)
      * @return void
      */
     public function set($key, $value = null)
@@ -61,9 +61,9 @@ class SessionData
     /**
      * Increments one or multiple session values by a specified amount
      *
-     * @param  string|array $key The key to increment or an array with multiple keys
-     * @param  integer      $by  Increment by which amount?
-     * @param  integer      $max Maximum amount (value is not incremented further)
+     * @param string|array $key The key to increment or an array with multiple keys
+     * @param int $by Increment by which amount?
+     * @param int $max Maximum amount (value is not incremented further)
      * @return void
      */
     public function increment($key, int $by = 1, $max = null)
@@ -115,9 +115,9 @@ class SessionData
     /**
      * Decrements one or multiple session values by a specified amount
      *
-     * @param  string|array $key The key to decrement or an array with multiple keys
-     * @param  integer      $by  Decrement by which amount?
-     * @param  integer      $min Minimum amount (value is not decremented further)
+     * @param string|array $key The key to decrement or an array with multiple keys
+     * @param int $by Decrement by which amount?
+     * @param int $min Minimum amount (value is not decremented further)
      * @return void
      */
     public function decrement($key, int $by = 1, $min = null)
@@ -169,8 +169,8 @@ class SessionData
     /**
      * Returns one or all session values by key
      *
-     * @param  string|null $key     The key to get or null for the entire data array
-     * @param  mixed       $default Optional default value to return if the key is not defined
+     * @param string|null $key The key to get or null for the entire data array
+     * @param mixed $default Optional default value to return if the key is not defined
      * @return mixed
      */
     public function get($key = null, $default = null)
@@ -190,8 +190,8 @@ class SessionData
     /**
      * Retrieves a value and removes it afterwards
      *
-     * @param  string $key     The key to get
-     * @param  mixed  $default Optional default value to return if the key is not defined
+     * @param string $key The key to get
+     * @param mixed $default Optional default value to return if the key is not defined
      * @return mixed
      */
     public function pull(string $key, $default = null)
@@ -208,7 +208,7 @@ class SessionData
     /**
      * Removes one or multiple session values by key
      *
-     * @param  string|array $key The key to remove or an array with multiple keys
+     * @param string|array $key The key to remove or an array with multiple keys
      * @return void
      */
     public function remove($key)
@@ -245,7 +245,7 @@ class SessionData
      * Reloads the data array with the current session data
      * Only used internally
      *
-     * @param  array $data Currently stored session data
+     * @param array $data Currently stored session data
      * @return void
      */
     public function reload(array $data)

kirby/src/Session/SessionStore.php

@@ -17,18 +17,18 @@ abstract class SessionStore
      * Needs to make sure that the session does not already exist
      * and needs to reserve it by locking it exclusively.
      *
-     * @param  int    $expiryTime Timestamp
-     * @return string             Randomly generated session ID (without timestamp)
+     * @param int $expiryTime Timestamp
+     * @return string Randomly generated session ID (without timestamp)
      */
     abstract public function createId(int $expiryTime): string;
 
     /**
      * Checks if the given session exists
      *
-     * @param  int     $expiryTime Timestamp
-     * @param  string  $id         Session ID
-     * @return boolean             true:  session exists,
-     *                             false: session doesn't exist
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
+     * @return bool true:  session exists,
+     *              false: session doesn't exist
      */
     abstract public function exists(int $expiryTime, string $id): bool;
 
@@ -37,8 +37,8 @@ abstract class SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     abstract public function lock(int $expiryTime, string $id);
@@ -48,8 +48,8 @@ abstract class SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     abstract public function unlock(int $expiryTime, string $id);
@@ -59,8 +59,8 @@ abstract class SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return string
      */
     abstract public function get(int $expiryTime, string $id): string;
@@ -71,9 +71,9 @@ abstract class SessionStore
      * Needs to make sure that the session exists.
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
-     * @param  string $data       Session data to write
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
+     * @param string $data Session data to write
      * @return void
      */
     abstract public function set(int $expiryTime, string $id, string $data);
@@ -83,8 +83,8 @@ abstract class SessionStore
      *
      * Needs to throw an Exception on error.
      *
-     * @param  int    $expiryTime Timestamp
-     * @param  string $id         Session ID
+     * @param int $expiryTime Timestamp
+     * @param string $id Session ID
      * @return void
      */
     abstract public function destroy(int $expiryTime, string $id);

kirby/src/Session/Sessions.php

@@ -30,14 +30,11 @@ class Sessions
     /**
      * Creates a new Sessions instance
      *
-     * @param \Kirby\Session\SessionStore|string $store   SessionStore object or a path to the storage directory (uses the FileSessionStore)
-     * @param array               $options Optional additional options:
-     *                                     - `mode`:       Default token transmission mode (cookie, header or manual)
-     *                                                     Defaults to `cookie`
-     *                                     - `cookieName`: Name to use for the session cookie
-     *                                                     Defaults to `kirby_session`
-     *                                     - `gcInterval`: How often should the garbage collector be run?
-     *                                                     Integer or `false` for never; defaults to `100`
+     * @param \Kirby\Session\SessionStore|string $store SessionStore object or a path to the storage directory (uses the FileSessionStore)
+     * @param array $options Optional additional options:
+     *                       - `mode`: Default token transmission mode (cookie, header or manual); defaults to `cookie`
+     *                       - `cookieName`: Name to use for the session cookie; defaults to `kirby_session`
+     *                       - `gcInterval`: How often should the garbage collector be run?; integer or `false` for never; defaults to `100`
      */
     public function __construct($store, array $options = [])
     {
@@ -93,17 +90,12 @@ class Sessions
     /**
      * Creates a new empty session
      *
-     * @param  array   $options Optional additional options:
-     *                          - `mode`:       Token transmission mode (cookie or manual)
-     *                                          Defaults to default mode of the Sessions instance
-     *                          - `startTime`:  Time the session starts being valid (date string or timestamp)
-     *                                          Defaults to `now`
-     *                          - `expiryTime`: Time the session expires (date string or timestamp)
-     *                                          Defaults to `+ 2 hours`
-     *                          - `timeout`:    Activity timeout in seconds (integer or false for none)
-     *                                          Defaults to `1800` (half an hour)
-     *                          - `renewable`:  Should it be possible to extend the expiry date?
-     *                                          Defaults to `true`
+     * @param array $options Optional additional options:
+     *                       - `mode`: Token transmission mode (cookie or manual); defaults to default mode of the Sessions instance
+     *                       - `startTime`:  Time the session starts being valid (date string or timestamp); defaults to `now`
+     *                       - `expiryTime`: Time the session expires (date string or timestamp); defaults to `+ 2 hours`
+     *                       - `timeout`: Activity timeout in seconds (integer or false for none); defaults to `1800` (half an hour)
+     *                       - `renewable`: Should it be possible to extend the expiry date?; defaults to `true`
      * @return \Kirby\Session\Session
      */
     public function create(array $options = [])
@@ -119,8 +111,8 @@ class Sessions
     /**
      * Returns the specified Session object
      *
-     * @param  string $token Session token, either including or without the key
-     * @param  string $mode  Optional transmission mode override
+     * @param string $token Session token, either including or without the key
+     * @param string $mode Optional transmission mode override
      * @return \Kirby\Session\Session
      */
     public function get(string $token, string $mode = null)

kirby/src/Text/Markdown.php

@@ -56,8 +56,8 @@ class Markdown
     /**
      * Parses the given text and returns the HTML
      *
-     * @param  string $text
-     * @param  bool $inline
+     * @param string $text
+     * @param bool $inline
      * @return string
      */
     public function parse(string $text, bool $inline = false): string

kirby/src/Text/SmartyPants.php

@@ -115,7 +115,7 @@ class SmartyPants
     /**
      * Parses the given text
      *
-     * @param  string $text
+     * @param string $text
      * @return string
      */
     public function parse(string $text): string

kirby/src/Toolkit/A.php

@@ -51,11 +51,11 @@ class A
      * // result: ['cat' => 'miao', 'dog' => 'wuff'];
      * </code>
      *
-     * @param   array  $array   The source array
-     * @param   mixed  $key     The key to look for
-     * @param   mixed  $default Optional default value, which should be
-     *                          returned if no element has been found
-     * @return  mixed
+     * @param array $array The source array
+     * @param mixed $key The key to look for
+     * @param mixed $default Optional default value, which should be
+     *                       returned if no element has been found
+     * @return mixed
      */
     public static function get($array, $key, $default = null)
     {
@@ -130,12 +130,12 @@ class A
     /**
      * Merges arrays recursively
      *
-     * @param  array   $array1
-     * @param  array   $array2
-     * @param  boolean $mode   Behavior for elements with numeric keys;
-     *                         A::MERGE_APPEND:    elements are appended, keys are reset;
-     *                         A::MERGE_OVERWRITE: elements are overwritten, keys are preserved
-     *                         A::MERGE_REPLACE:   non-associative arrays are completely replaced
+     * @param array $array1
+     * @param array $array2
+     * @param bool $mode Behavior for elements with numeric keys;
+     *                   A::MERGE_APPEND:    elements are appended, keys are reset;
+     *                   A::MERGE_OVERWRITE: elements are overwritten, keys are preserved
+     *                   A::MERGE_REPLACE:   non-associative arrays are completely replaced
      * @return array
      */
     public static function merge($array1, $array2, $mode = A::MERGE_APPEND)
@@ -196,10 +196,10 @@ class A
      * // result: ['homer', 'marge', 'lisa'];
      * </code>
      *
-     * @param   array   $array   The source array
-     * @param   string  $key     The key name of the column to extract
-     * @return  array            The result array with all values
-     *                           from that column.
+     * @param array $array The source array
+     * @param string $key The key name of the column to extract
+     * @return array The result array with all values
+     *               from that column.
      */
     public static function pluck(array $array, string $key)
     {
@@ -243,8 +243,8 @@ class A
      * // ];
      * </code>
      *
-     * @param   array  $array The source array
-     * @return  array  The shuffled result array
+     * @param array $array The source array
+     * @return array The shuffled result array
      */
     public static function shuffle(array $array): array
     {
@@ -275,8 +275,8 @@ class A
      * // first: 'miao'
      * </code>
      *
-     * @param   array  $array    The source array
-     * @return  mixed            The first element
+     * @param array $array The source array
+     * @return mixed The first element
      */
     public static function first(array $array)
     {
@@ -297,8 +297,8 @@ class A
      * // last: 'tweet'
      * </code>
      *
-     * @param   array  $array    The source array
-     * @return  mixed            The last element
+     * @param array $array The source array
+     * @return mixed The last element
      */
     public static function last(array $array)
     {
@@ -326,12 +326,12 @@ class A
      * // ];
      * </code>
      *
-     * @param   array  $array  The source array
-     * @param   int    $limit  The number of elements the array should
-     *                         contain after filling it up.
-     * @param   mixed  $fill   The element, which should be used to
-     *                         fill the array
-     * @return  array          The filled-up result array
+     * @param array $array The source array
+     * @param int $limit The number of elements the array should
+     *                   contain after filling it up.
+     * @param mixed $fill The element, which should be used to
+     *                    fill the array
+     * @return array The filled-up result array
      */
     public static function fill(array $array, int $limit, $fill = 'placeholder'): array
     {
@@ -394,10 +394,10 @@ class A
      * // ];
      * </code>
      *
-     * @param   array  $array    The source array
-     * @param   array  $required An array of required keys
-     * @return  array            An array of missing fields. If this
-     *                           is empty, nothing is missing.
+     * @param array $array The source array
+     * @param array $required An array of required keys
+     * @return array An array of missing fields. If this
+     *               is empty, nothing is missing.
      */
     public static function missing(array $array, array $required = []): array
     {
@@ -451,13 +451,13 @@ class A
      *
      * </code>
      *
-     * @param   array   $array The source array
-     * @param   string  $field The name of the column
-     * @param   string  $direction desc (descending) or asc (ascending)
-     * @param   int     $method A PHP sort method flag or 'natural' for
-     *                          natural sorting, which is not supported in
-     *                          PHP by sort flags
-     * @return  array   The sorted array
+     * @param array $array The source array
+     * @param string $field The name of the column
+     * @param string $direction desc (descending) or asc (ascending)
+     * @param int $method A PHP sort method flag or 'natural' for
+     *                    natural sorting, which is not supported in
+     *                    PHP by sort flags
+     * @return array The sorted array
      */
     public static function sort(array $array, string $field, string $direction = 'desc', $method = SORT_REGULAR): array
     {
@@ -500,8 +500,8 @@ class A
      * // returns: true
      * </code>
      *
-     * @param   array    $array The array to analyze
-     * @return  boolean  true: The array is associative false: It's not
+     * @param array $array The array to analyze
+     * @return bool true: The array is associative false: It's not
      */
     public static function isAssociative(array $array): bool
     {
@@ -511,9 +511,9 @@ class A
     /**
      * Returns the average value of an array
      *
-     * @param   array  $array The source array
-     * @param   int    $decimals The number of decimals to return
-     * @return  float  The average value
+     * @param array $array The source array
+     * @param int $decimals The number of decimals to return
+     * @return float The average value
      */
     public static function average(array $array, int $decimals = 0): float
     {
@@ -568,8 +568,8 @@ class A
      * ]);
      * </code>
      *
-     * @param  array $array
-     * @param  array $update
+     * @param array $array
+     * @param array $update
      * @return array
      */
     public static function update(array $array, array $update): array

kirby/src/Toolkit/Collection.php

@@ -35,8 +35,8 @@ class Collection extends Iterator implements Countable
     /**
      * Magic getter function
      *
-     * @param  string $key
-     * @param  mixed  $arguments
+     * @param string $key
+     * @param mixed $arguments
      * @return mixed
      */
     public function __call(string $key, $arguments)
@@ -67,7 +67,7 @@ class Collection extends Iterator implements Countable
     /**
      * Low-level getter for elements
      *
-     * @param  mixed $key
+     * @param mixed $key
      * @return mixed
      */
     public function __get($key)
@@ -82,8 +82,8 @@ class Collection extends Iterator implements Countable
     /**
      * Low-level setter for elements
      *
-     * @param string  $key    string or array
-     * @param mixed   $value
+     * @param string $key string or array
+     * @param mixed $value
      */
     public function __set(string $key, $value)
     {
@@ -114,8 +114,8 @@ class Collection extends Iterator implements Countable
     /**
      * Appends an element
      *
-     * @param  mixed      $key
-     * @param  mixed      $item
+     * @param mixed $key
+     * @param mixed $item
      * @return \Kirby\Toolkit\Collection
      */
     public function append(...$args)
@@ -133,9 +133,9 @@ class Collection extends Iterator implements Countable
      * Creates chunks of the same size.
      * 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
+     * @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
      */
     public function chunk(int $size)
     {
@@ -175,7 +175,7 @@ class Collection extends Iterator implements Countable
     /**
      * Getter and setter for the data
      *
-     * @param  array $data
+     * @param array $data
      * @return array|Collection
      */
     public function data(array $data = null)
@@ -422,8 +422,8 @@ class Collection extends Iterator implements Countable
     /**
      * Getter
      *
-     * @param  mixed  $key
-     * @param  mixed  $default
+     * @param mixed $key
+     * @param mixed $default
      * @return mixed
      */
     public function get($key, $default = null)
@@ -439,7 +439,7 @@ class Collection extends Iterator implements Countable
      *
      * @param array|object $item
      * @param string $attribute
-     * @param boolean $split
+     * @param bool $split
      * @param mixed $related
      * @return mixed
      */
@@ -542,10 +542,38 @@ class Collection extends Iterator implements Countable
         });
     }
 
+    /**
+     * Returns a Collection with the intersection of the given elements
+     *
+     * @param \Kirby\Toolkit\Collection $other
+     * @return \Kirby\Toolkit\Collection
+     */
+    public function intersection($other)
+    {
+        return $other->find($this->keys());
+    }
+
+    /**
+     * Checks if there is an intersection between the given collection and this collection
+     *
+     * @param \Kirby\Toolkit\Collection $other
+     * @return bool
+     */
+    public function intersects($other): bool
+    {
+        foreach ($this->keys() as $key) {
+            if ($other->has($key)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Checks if the number of elements is zero
      *
-     * @return boolean
+     * @return bool
      */
     public function isEmpty(): bool
     {
@@ -555,7 +583,7 @@ class Collection extends Iterator implements Countable
     /**
      * Checks if the number of elements is even
      *
-     * @return boolean
+     * @return bool
      */
     public function isEven(): bool
     {
@@ -565,7 +593,7 @@ class Collection extends Iterator implements Countable
     /**
      * Checks if the number of elements is more than zero
      *
-     * @return boolean
+     * @return bool
      */
     public function isNotEmpty(): bool
     {
@@ -575,7 +603,7 @@ class Collection extends Iterator implements Countable
     /**
      * Checks if the number of elements is odd
      *
-     * @return boolean
+     * @return bool
      */
     public function isOdd(): bool
     {
@@ -596,7 +624,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
+     * @param int $limit The number of elements to return
      * @return \Kirby\Toolkit\Collection
      */
     public function limit(int $limit)
@@ -607,7 +635,7 @@ class Collection extends Iterator implements Countable
     /**
      * Map a function to each element
      *
-     * @param  callable $callback
+     * @param callable $callback
      * @return \Kirby\Toolkit\Collection
      */
     public function map(callable $callback)
@@ -619,7 +647,7 @@ class Collection extends Iterator implements Countable
     /**
      * Returns the nth element from the collection
      *
-     * @param integer $n
+     * @param int $n
      * @return mixed
      */
     public function nth(int $n)
@@ -645,7 +673,7 @@ class Collection extends Iterator implements Countable
     /**
      * Returns a new object starting from the given offset
      *
-     * @param  int        $offset  The index to start from
+     * @param int $offset The index to start from
      * @return \Kirby\Toolkit\Collection
      */
     public function offset(int $offset)
@@ -710,8 +738,8 @@ class Collection extends Iterator implements Countable
     /**
      * Prepends an element to the data array
      *
-     * @param  mixed       $key
-     * @param  mixed       $item
+     * @param mixed $key
+     * @param mixed $item
      * @return self
      */
     public function prepend(...$args)
@@ -790,8 +818,8 @@ class Collection extends Iterator implements Countable
     /**
      * Adds a new element to the collection
      *
-     * @param  mixed  $key    string or array
-     * @param  mixed  $value
+     * @param mixed $key string or array
+     * @param mixed $value
      * @return self
      */
     public function set($key, $value = null)
@@ -830,8 +858,8 @@ class Collection extends Iterator implements Countable
     /**
      * Returns a slice of the object
      *
-     * @param  int        $offset  The optional index to start the slice from
-     * @param  int        $limit   The optional number of elements to return
+     * @param int $offset The optional index to start the slice from
+     * @param int $limit The optional number of elements to return
      * @return \Kirby\Toolkit\Collection
      */
     public function slice(int $offset = 0, int $limit = null)
@@ -868,10 +896,10 @@ class Collection extends Iterator implements Countable
     /**
      * Sorts the elements by any number of fields
      *
-     * @param   $field      string|callable  Field name or value callback to sort by
-     * @param   $direction  string           asc or desc
-     * @param   $method     int              The sort flag, SORT_REGULAR, SORT_NUMERIC etc.
-     * @return  Collection
+     * @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
      */
     public function sortBy()
     {
@@ -1027,10 +1055,34 @@ class Collection extends Iterator implements Countable
         return array_values($this->data);
     }
 
+    /**
+     * The when method only executes the given Closure when the first parameter
+     * is true. If the first parameter is false, the Closure will not be executed.
+     * You may pass another Closure as the third parameter to the when method.
+     * This Closure will execute if the first parameter evaluates as false
+     *
+     * @param mixed $condition
+     * @param Closure $callback
+     * @param Closure $fallback
+     * @return mixed
+     */
+    public function when($condition, Closure $callback, Closure $fallback = null)
+    {
+        if ($condition) {
+            return $callback->call($this, $condition);
+        }
+
+        if ($fallback !== null) {
+            return $fallback->call($this, $condition);
+        }
+
+        return $this;
+    }
+
     /**
      * Alias for $this->not()
      *
-     * @param  string ...$keys any number of keys, passed as individual arguments
+     * @param string ...$keys any number of keys, passed as individual arguments
      * @return \Kirby\Toolkit\Collection
      */
     public function without(...$keys)