Add request model support

Author: abnegate

composer.json

@@ -22,15 +22,15 @@
         "bench": "vendor/bin/phpbench run --report=benchmark"
     },
     "require": {
-        "php": ">=8.1",
+        "php": ">=8.3",
         "utopia-php/compression": "0.1.*",
         "utopia-php/telemetry": "0.1.*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.5.25",
-        "laravel/pint": "^1.2",
-        "phpstan/phpstan": "^1.10",
-        "phpbench/phpbench": "^1.2"
+        "phpunit/phpunit": "9.*",
+        "laravel/pint": "1.*",
+        "phpstan/phpstan": "1.*",
+        "phpbench/phpbench": "1.*"
     },
     "config": {
         "allow-plugins": {

src/App.php

@@ -693,21 +693,50 @@ protected function getArguments(Hook $hook, array $values, array $requestParams)
 
             $value = $existsInValues ? $values[$key] : $arg;
 
-            if (!$param['skipValidation']) {
-                if (!$paramExists && !$param['optional']) {
-                    throw new Exception('Param "' . $key . '" is not optional.', 400);
-                }
+            if (!$param['skipValidation']&& !$paramExists && !$param['optional']) {
+                throw new Exception('Param "' . $key . '" is not optional.', 400);
+            }
 
-                if ($paramExists) {
-                    $this->validate($key, $param, $value);
+            if ($param['model'] && $paramExists) {
+                $model = $param['model'];
+
+                if (!\is_string($model) || !\class_exists($model)) {
+                    throw new Exception('Model class does not exist: ' . $model, 500);
+                }
+                if (!\is_a($model, Model::class, true)) {
+                    throw new Exception('Model class is not an instance of Utopia\\Model', 500);
+                }
+                if (($value === null || $value === '') && $param['optional']) {
+                    $value = null;
+                }
+                if (\is_string($value) && $value !== '') {
+                    try {
+                        $value = \json_decode($value, true, flags: JSON_THROW_ON_ERROR);
+                    } catch (\Throwable $e) {
+                        throw new Exception('Failed to parse JSON for model param "' . $key . '": ' . $e->getMessage(), 400);
+                    }
+                }
+                if (!\is_array($value) && $value !== null && $value !== '') {
+                    throw new Exception('Model param "' . $key . '" must be a JSON string, or an array', 400);
+                }
+                if (\is_array($value)) {
+                    try {
+                        $value = $model::fromArray($value);
+                    } catch (\Throwable $e) {
+                        throw new Exception('Failed to create model instance for param "' . $key . '": ' . $e->getMessage(), 400);
+                    }
                 }
             }
 
+            if (!$param['skipValidation'] && $paramExists && $value !== null && $value !== '') {
+                $this->validate($key, $param, $value);
+            }
+
             $hook->setParamValue($key, $value);
             $arguments[$param['order']] = $value;
         }
 
-        foreach ($hook->getInjections() as $key => $injection) {
+        foreach ($hook->getInjections() as $injection) {
             $arguments[$injection['order']] = $this->getResource($injection['name']);
         }
 

src/Hook.php

@@ -190,18 +190,19 @@ public function inject(string $injection): static
     /**
      * Add Param
      *
-     * @param  string  $key
-     * @param  mixed  $default
-     * @param  Validator|callable  $validator
-     * @param  string  $description
-     * @param  bool  $optional
-     * @param  array  $injections
-     * @param  bool  $skipValidation
-     * @param  bool  $deprecated
-     * @param  string  $example
+     * @param string $key
+     * @param mixed $default
+     * @param Validator|callable $validator
+     * @param string $description
+     * @param bool $optional
+     * @param array $injections
+     * @param bool $skipValidation
+     * @param bool $deprecated
+     * @param string $example
+     * @param string|null $model
      * @return static
      */
-    public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = ''): static
+    public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = '', ?string $model = null): static
     {
         $this->params[$key] = [
             'default' => $default,
@@ -212,6 +213,7 @@ public function param(string $key, mixed $default, Validator|callable $validator
             'skipValidation' => $skipValidation,
             'deprecated' => $deprecated,
             'example' => $example,
+            'model' => $model,
             'value' => null,
             'order' => count($this->params) + count($this->injections),
         ];

src/Model.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Utopia;
+
+interface Model
+{
+    public static function fromArray(array $value): static;
+}