Upgrade to 3.2.0

kirby/src/Cms/Api.php

@@ -7,16 +7,37 @@ use Kirby\Exception\InvalidArgumentException;
 use Kirby\Exception\NotFoundException;
 use Kirby\Toolkit\Str;
 
+/**
+ * Api
+ *
+ * @package   Kirby Cms
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier GmbH
+ * @license   https://getkirby.com/license
+ */
 class Api extends BaseApi
 {
+    /**
+     * @var App
+     */
     protected $kirby;
 
+    /**
+     * Execute an API call for the given path,
+     * request method and optional request data
+     *
+     * @param string $path
+     * @param string $method
+     * @param array $requestData
+     * @return mixed
+     */
     public function call(string $path = null, string $method = 'GET', array $requestData = [])
     {
         $this->setRequestMethod($method);
         $this->setRequestData($requestData);
 
-        if ($languageCode = $this->requestHeaders('x-language')) {
+        if ($languageCode = $this->language()) {
             $this->kirby->setCurrentLanguage($languageCode);
         }
 
@@ -27,6 +48,12 @@ class Api extends BaseApi
         return parent::call($path, $method, $requestData);
     }
 
+    /**
+     * @param mixed $model
+     * @param string $name
+     * @param string $path
+     * @return mixed
+     */
     public function fieldApi($model, string $name, string $path = null)
     {
         $form       = Form::for($model);
@@ -59,6 +86,14 @@ class Api extends BaseApi
         return $fieldApi->call($path, $this->requestMethod(), $this->requestData());
     }
 
+    /**
+     * Returns the file object for the given
+     * parent path and filename
+     *
+     * @param string $path Path to file's parent model
+     * @param string $filename Filename
+     * @return Kirby\Cms\File|null
+     */
     public function file(string $path = null, string $filename)
     {
         $filename = urldecode($filename);
@@ -75,12 +110,22 @@ class Api extends BaseApi
         ]);
     }
 
+    /**
+     * Returns the model's object for the given path
+     *
+     * @param string $path Path to parent model
+     * @return Kirby\Cms\Model|null
+     */
     public function parent(string $path)
     {
-        $modelType  = $path === 'site' ? 'site' : dirname($path);
+        $modelType  = $path === 'site' ? 'site' : trim(dirname($path), '/');
         $modelTypes = ['site' => 'site', 'users' => 'user', 'pages' => 'page'];
         $modelName  = $modelTypes[$modelType] ?? null;
 
+        if (Str::endsWith($modelType, '/files') === true) {
+            $modelName = 'file';
+        }
+
         if ($modelName === null) {
             throw new InvalidArgumentException('Invalid file model type');
         }
@@ -91,7 +136,13 @@ class Api extends BaseApi
             $modelId = basename($path);
 
             if ($modelName === 'page') {
-                $modelId = str_replace('+', '/', $modelId);
+                $modelId = str_replace(['+', ' '], '/', $modelId);
+            }
+
+            if ($modelName === 'file') {
+                if ($model = $this->file(...explode('/files/', $path))) {
+                    return $model;
+                }
             }
         }
 
@@ -104,16 +155,32 @@ class Api extends BaseApi
         ]);
     }
 
+    /**
+     * Returns the Kirby instance
+     *
+     * @return Kirby\Cms\App
+     */
     public function kirby()
     {
         return $this->kirby;
     }
 
-    public function language()
+    /**
+     * Returns the language request header
+     *
+     * @return string|null
+     */
+    public function language(): ?string
     {
-        return $this->requestHeaders('x-language');
+        return get('language') ?? $this->requestHeaders('x-language');
     }
 
+    /**
+    * Returns the page object for the given id
+    *
+    * @param string $id Page's id
+    * @return Kirby\Cms\Page|null
+    */
     public function page(string $id)
     {
         $id   = str_replace('+', '/', $id);
@@ -138,17 +205,33 @@ class Api extends BaseApi
         ], $options));
     }
 
+    /**
+     * @param Kirby\Cms\App $kirby
+     */
     protected function setKirby(App $kirby)
     {
         $this->kirby = $kirby;
         return $this;
     }
 
+    /**
+     * Returns the site object
+     *
+     * @return Kirby\Cms\Site
+     */
     public function site()
     {
         return $this->kirby->site();
     }
 
+    /**
+     * Returns the user object for the given id or
+     * returns the current authenticated user if no
+     * id is passed
+     *
+     * @param string $id User's id
+     * @return Kirby\Cms\User|null
+     */
     public function user(string $id = null)
     {
         // get the authenticated user
@@ -169,6 +252,11 @@ class Api extends BaseApi
         ]);
     }
 
+    /**
+     * Returns the users collection
+     *
+     * @return Kirby\Cms\Users
+     */
     public function users()
     {
         return $this->kirby->users();