feat: struct value type

Ark4ne · Ark4ne · commit a2396ae43ca8 · 2025-02-14T15:35:09.000+01:00
diff --git a/src/Descriptors/Describer.php b/src/Descriptors/Describer.php
@@ -151,12 +151,12 @@ abstract public function retriever(): null|string|Closure;
      *
      * @return int|string
      */
-    public static function retrieveName(mixed $value, int|string $key): int|string
+    public static function retrieveName(mixed $value, int|string $key, null|string $prefix = null): int|string
     {
         if (is_int($key) && $value instanceof self && is_string($retriever = $value->retriever())) {
-            return $retriever;
+            return $prefix ? $prefix . '.' . $retriever : $retriever;
         }
 
-        return $key;
+        return $prefix ? $prefix . '.' . $key : $key;
     }
 }
diff --git a/src/Descriptors/Values.php b/src/Descriptors/Values.php
@@ -2,16 +2,17 @@
 
 namespace Ark4ne\JsonApi\Descriptors;
 
-use Ark4ne\JsonApi\Descriptors\Relations\RelationMany;
-use Ark4ne\JsonApi\Descriptors\Relations\RelationOne;
-use Ark4ne\JsonApi\Descriptors\Values\{ValueArray,
+use Ark4ne\JsonApi\Descriptors\Values\{
+    ValueArray,
     ValueBool,
     ValueDate,
     ValueEnum,
     ValueFloat,
     ValueInteger,
     ValueMixed,
-    ValueString};
+    ValueString,
+    ValueStruct
+};
 use Closure;
 
 /**
@@ -98,4 +99,14 @@ protected function enum(null|string|Closure $attribute = null): ValueEnum
     {
         return new ValueEnum($attribute);
     }
+
+    /**
+     * @param Closure(T):iterable<string, \Closure|mixed>|iterable<array-key, \Ark4ne\JsonApi\Descriptors\Values\Value> $attribute
+     *
+     * @return \Ark4ne\JsonApi\Descriptors\Values\ValueStruct<T>
+     */
+    protected function struct(Closure $attribute = null): ValueStruct
+    {
+        return new ValueStruct($attribute);
+    }
 }
diff --git a/src/Descriptors/Values/Value.php b/src/Descriptors/Values/Value.php
@@ -108,7 +108,7 @@ public function resolveFor(Request $request, mixed $model, string $field): mixed
 
         return $value === null && $this->nullable
             ? null
-            : $this->value($value);
+            : $this->value($value, $request);
     }
 
     protected function check(Request $request, mixed $model, string $attribute): bool
@@ -120,5 +120,5 @@ protected function check(Request $request, mixed $model, string $attribute): boo
         return parent::check($request, $model, $attribute);
     }
 
-    abstract protected function value(mixed $of): mixed;
+    abstract protected function value(mixed $of, Request $request): mixed;
 }
diff --git a/src/Descriptors/Values/ValueArray.php b/src/Descriptors/Values/ValueArray.php
@@ -2,6 +2,7 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Illuminate\Http\Request;
 use Illuminate\Support\Collection;
 
 /**
@@ -12,10 +13,10 @@ class ValueArray extends Value
 {
     /**
      * @param mixed $of
-     *
+     * @param Request $request
      * @return array<array-key, mixed>
      */
-    public function value(mixed $of): array
+    public function value(mixed $of, Request $request): array
     {
         return (new Collection($of))->toArray();
     }
diff --git a/src/Descriptors/Values/ValueBool.php b/src/Descriptors/Values/ValueBool.php
@@ -2,13 +2,15 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Illuminate\Http\Request;
+
 /**
  * @template T
  * @extends Value<T>
  */
 class ValueBool extends Value
 {
-    public function value(mixed $of): bool
+    public function value(mixed $of, Request $request): bool
     {
         return (bool)$of;
     }
diff --git a/src/Descriptors/Values/ValueDate.php b/src/Descriptors/Values/ValueDate.php
@@ -6,6 +6,7 @@
 use Closure;
 use DateTime;
 use DateTimeInterface;
+use Illuminate\Http\Request;
 
 /**
  * @template T
@@ -31,7 +32,7 @@ public function format(string $format): static
     /**
      * @throws \Exception
      */
-    public function value(mixed $of): string
+    public function value(mixed $of, Request $request): string
     {
         if ($of === null) {
             return (new DateTime("@0"))->format($this->format);
diff --git a/src/Descriptors/Values/ValueEnum.php b/src/Descriptors/Values/ValueEnum.php
@@ -3,6 +3,7 @@
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
 use BackedEnum;
+use Illuminate\Http\Request;
 use UnitEnum;
 
 /**
@@ -11,7 +12,7 @@
  */
 class ValueEnum extends Value
 {
-    protected function value(mixed $of): mixed
+    protected function value(mixed $of, Request $request): mixed
     {
         if ($of instanceof BackedEnum) return $of->value;
         if ($of instanceof UnitEnum) return $of->name;
diff --git a/src/Descriptors/Values/ValueFloat.php b/src/Descriptors/Values/ValueFloat.php
@@ -4,6 +4,7 @@
 
 use Ark4ne\JsonApi\Support\Config;
 use Closure;
+use Illuminate\Http\Request;
 
 /**
  * @template T
@@ -26,7 +27,7 @@ public function precision(int $precision): static
         return $this;
     }
 
-    public function value(mixed $of): float
+    public function value(mixed $of, Request $request): float
     {
         if (isset($this->precision)) {
             $precision = 10 ** $this->precision;
diff --git a/src/Descriptors/Values/ValueInteger.php b/src/Descriptors/Values/ValueInteger.php
@@ -2,13 +2,15 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Illuminate\Http\Request;
+
 /**
  * @template T
  * @extends Value<T>
  */
 class ValueInteger extends Value
 {
-    public function value(mixed $of): int
+    public function value(mixed $of, Request $request): int
     {
         return (int)$of;
     }
diff --git a/src/Descriptors/Values/ValueMixed.php b/src/Descriptors/Values/ValueMixed.php
@@ -2,13 +2,15 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Illuminate\Http\Request;
+
 /**
  * @template T
  * @extends Value<T>
  */
 class ValueMixed extends Value
 {
-    public function value(mixed $of): mixed
+    public function value(mixed $of, Request $request): mixed
     {
         return $of;
     }
diff --git a/src/Descriptors/Values/ValueString.php b/src/Descriptors/Values/ValueString.php
@@ -2,13 +2,15 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Illuminate\Http\Request;
+
 /**
  * @template T
  * @extends Value<T>
  */
 class ValueString extends Value
 {
-    public function value(mixed $of): string
+    public function value(mixed $of, Request $request): string
     {
         return (string)$of;
     }
diff --git a/src/Descriptors/Values/ValueStruct.php b/src/Descriptors/Values/ValueStruct.php
@@ -0,0 +1,45 @@
+<?php
+
+namespace Ark4ne\JsonApi\Descriptors\Values;
+
+use Ark4ne\JsonApi\Descriptors\Resolver;
+use Ark4ne\JsonApi\Support\Values;
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Collection;
+
+/**
+ * @template T
+ * @extends Value<T>
+ */
+class ValueStruct extends Value
+{
+    use Resolver;
+
+    protected mixed $resource;
+
+    public function __construct(Closure $values)
+    {
+        parent::__construct($values);
+    }
+
+    public function resolveFor(Request $request, mixed $model, string $field): mixed
+    {
+        $this->resource = $model;
+
+        return parent::resolveFor($request, $model, $field);
+    }
+
+    /**
+     * @param mixed $of
+     * @param Request $request
+     *
+     * @return array<array-key, mixed>
+     */
+    public function value(mixed $of, Request $request): array
+    {
+        $attributes = Values::mergeValues($this->resolveValues($request, Values::mergeValues($of)));
+
+        return (new Collection($attributes))->toArray();
+    }
+}
diff --git a/src/Resources/Concerns/Attributes.php b/src/Resources/Concerns/Attributes.php
@@ -2,6 +2,7 @@
 
 namespace Ark4ne\JsonApi\Resources\Concerns;
 
+use Ark4ne\JsonApi\Support\Arr;
 use Ark4ne\JsonApi\Support\Fields;
 use Illuminate\Http\Request;
 
@@ -58,7 +59,7 @@ private function requestedAttributes(Request $request): array
 
             $attributes = null === $fields
                 ? $attributes
-                : array_intersect_key($attributes, array_fill_keys($fields, true));
+                : Arr::intersectKeyStruct($attributes, Arr::undot(array_fill_keys($fields, true)));
 
             return array_map('\value', $attributes);
         });
diff --git a/src/Resources/Concerns/PrepareData.php b/src/Resources/Concerns/PrepareData.php
@@ -28,7 +28,6 @@ trait PrepareData
      */
     protected function mergeValues(iterable $data): iterable
     {
-
         return Values::mergeValues($data);
     }
 
diff --git a/src/Resources/Concerns/Schema.php b/src/Resources/Concerns/Schema.php
@@ -5,6 +5,7 @@
 use Ark4ne\JsonApi\Descriptors\Describer;
 use Ark4ne\JsonApi\Descriptors\Relations\Relation;
 use Ark4ne\JsonApi\Descriptors\Resolver;
+use Ark4ne\JsonApi\Descriptors\Values\ValueStruct;
 use Ark4ne\JsonApi\Resources\Skeleton;
 use Ark4ne\JsonApi\Support\FakeModel;
 use Ark4ne\JsonApi\Support\Values;
@@ -37,9 +38,16 @@ public static function schema(null|Request $request = null): Skeleton
         );
 
         $schema->fields = (new Collection(Values::mergeValues($resource->toAttributes($request))))
-            ->map(fn($value, $key) => Describer::retrieveName($value, $key))
-            ->values()
-            ->all();
+            ->flatMap(function ($value, $key) use ($resource) {
+                $collection = (new Collection([Describer::retrieveName($value, $key) => true]));
+
+                if ($value instanceof ValueStruct) {
+                    return $collection->merge(self::structFields($resource, $key, $value, $key));
+                }
+
+                return $collection;
+            })
+            ->keys()->all();
 
         foreach (Values::mergeValues($resource->toRelationships($request)) as $name => $relation) {
             if ($relation instanceof Relation) {
@@ -83,4 +91,18 @@ private static function new(): static
 
         return $instance;
     }
+
+    private static function structFields(mixed $resource, string $key, ValueStruct $struct, null|string $prefix = null): Collection
+    {
+        return (new Collection(Values::mergeValues(($struct->retriever())($resource, $key))))
+            ->flatMap(function($value, $key) use ($resource, $prefix) {
+                $prefixed = Describer::retrieveName($value, $key, $prefix);
+
+                if ($value instanceof ValueStruct) {
+                    return self::structFields($resource, $key, $value, $prefixed);
+                }
+
+                return [$prefixed => $value];
+            });
+    }
 }
diff --git a/src/Support/Arr.php b/src/Support/Arr.php
@@ -163,6 +163,28 @@ public static function apply(array &$array, string $path, mixed $value, null|str
         return $array;
     }
 
+    /**
+     * @template TKey as array-key
+     * @template TValue
+     *
+     * @param array<TKey, TValue> $array
+     * @param array<array-key, mixed> $struct
+     *
+     * @return array<TKey, TValue>
+     */
+    public static function intersectKeyStruct(array $array, array $struct): array
+    {
+        $res = array_intersect_key($array, $struct);
+
+        foreach ($res as $key => $value) {
+            if (is_array($value) && is_array($struct[$key])) {
+                $res[$key] = self::intersectKeyStruct($value, $struct[$key]);
+            }
+        }
+
+        return $res;
+    }
+
     /**
      * @template TKey as array-key
      * @template TValue
diff --git a/tests/Feature/SchemaTest.php b/tests/Feature/SchemaTest.php
@@ -20,6 +20,17 @@ public function testSchema()
             'with-apply-conditional-raw',
             'with-apply-conditional-closure',
             'with-apply-conditional-value',
+            'struct-set',
+            'struct-set.name',
+            'struct-set.email',
+            'struct-set.casted',
+            'struct-set.with-apply-conditional-raw',
+            'struct-set.closure',
+            'struct-set.missing',
+            'struct-set.sub-struct.int',
+            'struct-set.sub-struct.float',
+            'struct-set.third-struct.int',
+            'struct-set.third-struct.float',
         ]);
         $post = new Skeleton(PostResource::class, 'post', ['state', 'title', 'content']);
         $comment = new Skeleton(CommentResource::class, 'comment', ['content']);
diff --git a/tests/Feature/User/ResourceTest.php b/tests/Feature/User/ResourceTest.php
diff --git a/tests/Unit/Descriptors/ValueTest.php b/tests/Unit/Descriptors/ValueTest.php
diff --git a/tests/app/Http/Resources/UserResource.php b/tests/app/Http/Resources/UserResource.php

Original file line number	Diff line number	Diff line change
`@@ -151,12 +151,12 @@ abstract public function retriever(): null\|string\|Closure;`
`151`	`151`	`*`
`152`	`152`	`* @return int\|string`
`153`	`153`	`*/`
`154`		`- public static function retrieveName(mixed $value, int\|string $key): int\|string`
	`154`	`+ public static function retrieveName(mixed $value, int\|string $key, null\|string $prefix = null): int\|string`
`155`	`155`	`{`
`156`	`156`	`if (is_int($key) && $value instanceof self && is_string($retriever = $value->retriever())) {`
`157`		`- return $retriever;`
	`157`	`+ return $prefix ? $prefix . '.' . $retriever : $retriever;`
`158`	`158`	`}`
`159`	`159`
`160`		`- return $key;`
	`160`	`+ return $prefix ? $prefix . '.' . $key : $key;`
`161`	`161`	`}`
`162`	`162`	`}`
Original file line number	Diff line number	Diff line change
`@@ -108,7 +108,7 @@ public function resolveFor(Request $request, mixed $model, string $field): mixed`
`108`	`108`
`109`	`109`	`return $value === null && $this->nullable`
`110`	`110`	`? null`
`111`		`- : $this->value($value);`
	`111`	`+ : $this->value($value, $request);`
`112`	`112`	`}`
`113`	`113`
`114`	`114`	`protected function check(Request $request, mixed $model, string $attribute): bool`
`@@ -120,5 +120,5 @@ protected function check(Request $request, mixed $model, string $attribute): boo`
`120`	`120`	`return parent::check($request, $model, $attribute);`
`121`	`121`	`}`
`122`	`122`
`123`		`- abstract protected function value(mixed $of): mixed;`
	`123`	`+ abstract protected function value(mixed $of, Request $request): mixed;`
`124`	`124`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`
`3`	`3`	`namespace Ark4ne\JsonApi\Descriptors\Values;`
`4`	`4`
	`5`	`+use Illuminate\Http\Request;`
`5`	`6`	`use Illuminate\Support\Collection;`
`6`	`7`
`7`	`8`	`/**`
`@@ -12,10 +13,10 @@ class ValueArray extends Value`
`12`	`13`	`{`
`13`	`14`	`/**`
`14`	`15`	`* @param mixed $of`
`15`		`- *`
	`16`	`+ * @param Request $request`
`16`	`17`	`* @return array<array-key, mixed>`
`17`	`18`	`*/`
`18`		`- public function value(mixed $of): array`
	`19`	`+ public function value(mixed $of, Request $request): array`
`19`	`20`	`{`
`20`	`21`	`return (new Collection($of))->toArray();`
`21`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,13 +2,15 @@`
`2`	`2`
`3`	`3`	`namespace Ark4ne\JsonApi\Descriptors\Values;`
`4`	`4`
	`5`	`+use Illuminate\Http\Request;`
	`6`	`+`
`5`	`7`	`/**`
`6`	`8`	`* @template T`
`7`	`9`	`* @extends Value<T>`
`8`	`10`	`*/`
`9`	`11`	`class ValueBool extends Value`
`10`	`12`	`{`
`11`		`- public function value(mixed $of): bool`
	`13`	`+ public function value(mixed $of, Request $request): bool`
`12`	`14`	`{`
`13`	`15`	`return (bool)$of;`
`14`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`	`namespace Ark4ne\JsonApi\Descriptors\Values;`
`4`	`4`
`5`	`5`	`use BackedEnum;`
	`6`	`+use Illuminate\Http\Request;`
`6`	`7`	`use UnitEnum;`
`7`	`8`
`8`	`9`	`/**`
`@@ -11,7 +12,7 @@`
`11`	`12`	`*/`
`12`	`13`	`class ValueEnum extends Value`
`13`	`14`	`{`
`14`		`- protected function value(mixed $of): mixed`
	`15`	`+ protected function value(mixed $of, Request $request): mixed`
`15`	`16`	`{`
`16`	`17`	`if ($of instanceof BackedEnum) return $of->value;`
`17`	`18`	`if ($of instanceof UnitEnum) return $of->name;`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`
`5`	`5`	`use Ark4ne\JsonApi\Support\Config;`
`6`	`6`	`use Closure;`
	`7`	`+use Illuminate\Http\Request;`
`7`	`8`
`8`	`9`	`/**`
`9`	`10`	`* @template T`
`@@ -26,7 +27,7 @@ public function precision(int $precision): static`
`26`	`27`	`return $this;`
`27`	`28`	`}`
`28`	`29`
`29`		`- public function value(mixed $of): float`
	`30`	`+ public function value(mixed $of, Request $request): float`
`30`	`31`	`{`
`31`	`32`	`if (isset($this->precision)) {`
`32`	`33`	`$precision = 10 ** $this->precision;`