Upgrade to 3.3.0

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)