Add support for mapping nested API relations in models

Introduces the $apiRelations property and castApiRelation method to ApiModelTrait, enabling flexible mapping and instantiation of nested relations from API responses. Adds comprehensive tests for recursive relation mapping using FolderModel and FileModel.

Author: KroderDev

src/Traits/ApiModelTrait.php

@@ -4,20 +4,76 @@
 
 use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Collection;
+use Kroderdev\LaravelMicroserviceCore\Interfaces\ApiModelContract;
 
 trait ApiModelTrait
 {
+    /**
+     * Relation mapping callbacks.
+     *
+     * Each key should be the relation name and the value either a class name,
+     * an array with the class name for collections, or a closure that returns
+     * the relation value.
+     */
+    protected static array $apiRelations = [];
+
     /**
      * Instantiate a model from raw API data.
      */
     public static function fromApiResponse(array $data): static
     {
         $instance = new static();
+
+        foreach (static::$apiRelations as $relation => $cast) {
+            if (array_key_exists($relation, $data)) {
+                $instance->setRelation(
+                    $relation,
+                    static::castApiRelation($cast, $data[$relation])
+                );
+                unset($data[$relation]);
+            }
+        }
+
         $instance->fill($data);
 
         return $instance;
     }
 
+    /**
+     * Cast the given relation value based on the provided definition.
+     */
+    protected static function castApiRelation(mixed $cast, mixed $value): mixed
+    {
+        if (is_callable($cast)) {
+            return $cast($value);
+        }
+
+        if (is_string($cast) && method_exists(static::class, $cast)) {
+            return static::$cast($value);
+        }
+
+        if (is_array($cast)) {
+            $class = $cast[0];
+
+            return collect($value)->map(fn ($item) => static::castApiRelation($class, $item));
+        }
+
+        if (is_string($cast) && class_exists($cast)) {
+            if (is_subclass_of($cast, ApiModelContract::class)) {
+                return $cast::fromApiResponse($value);
+            }
+
+            $model = new $cast();
+            if (method_exists($model, 'fill')) {
+                $model->fill($value);
+            }
+
+            return $model;
+        }
+
+        return $value;
+    }
+
     /**
      * Create a collection of models from an array of payloads.
      */

tests/Models/ApiModelTest.php

@@ -16,6 +16,35 @@ class RemoteUser extends ApiModel
     protected $fillable = ['id', 'name'];
 }
 
+class FileModel extends ApiModel
+{
+    protected $fillable = ['id', 'type', 'name', 'size'];
+}
+
+class FolderModel extends ApiModel
+{
+    protected $fillable = ['id', 'name', 'children'];
+
+    protected static array $apiRelations = [
+        'children' => 'mapChildren',
+    ];
+
+    protected static function mapChildren(array $items)
+    {
+        return collect($items)->map(function (array $data) {
+            if ($data['type'] === 'file') {
+                return FileModel::fromApiResponse($data);
+            }
+
+            if ($data['type'] === 'folder') {
+                return FolderModel::fromApiResponse($data);
+            }
+
+            throw new \UnexpectedValueException('Unknown child type: '.$data['type']);
+        });
+    }
+}
+
 class ApiModelTest extends TestCase
 {
     protected FakeGatewayClient $gateway;
@@ -179,4 +208,53 @@ public function delete_users_gateway()
             ['method' => 'DELETE', 'uri' => '/users/4'],
         ], $this->gateway->getCalls());
     }
+
+    
+    /** @test */
+    public function from_api_response_maps_nested_relations()
+    {
+        $data = [
+            'id' => 1,
+            'name' => 'root',
+            'type' => 'folder',
+            'children' => [
+                ['id' => 2, 'name' => 'file1.txt', 'type' => 'file', 'size' => 123],
+                [
+                    'id' => 3,
+                    'name' => 'docs',
+                    'type' => 'folder',
+                    'children' => [
+                        ['id' => 4, 'name' => 'file2.txt', 'type' => 'file', 'size' => 456],
+                        [
+                            'id' => 5,
+                            'name' => 'deep',
+                            'type' => 'folder',
+                            'children' => [
+                                ['id' => 6, 'name' => 'file3.txt', 'type' => 'file', 'size' => 789],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ];
+
+        $folder = FolderModel::fromApiResponse($data);
+
+        $this->assertEquals(1, $folder->id);
+        $this->assertCount(2, $folder->children);
+        $this->assertInstanceOf(FileModel::class, $folder->children[0]);
+        $this->assertEquals(123, $folder->children[0]->size);
+        $this->assertInstanceOf(FolderModel::class, $folder->children[1]);
+
+        $subfolder = $folder->children[1];
+        $this->assertCount(2, $subfolder->children);
+        $this->assertInstanceOf(FileModel::class, $subfolder->children[0]);
+        $this->assertInstanceOf(FolderModel::class, $subfolder->children[1]);
+
+        $deep = $subfolder->children[1];
+        $this->assertCount(1, $deep->children);
+        $this->assertInstanceOf(FileModel::class, $deep->children[0]);
+        $this->assertEquals('file3.txt', $deep->children[0]->name);
+        $this->assertEquals(789, $deep->children[0]->size);
+    }
 }