Add array item transformer that has wrapped array value in GetValue instance

- Make $getValue->makeInstance public.
- Renamed `ClosureArrayItemsTransformer` to `ArrayItemTransformer`
- Renamed `ClosureArrayTransformer` to `ArrayTransformer`
- Transformers `transform` method has new parameter `GetValue $getValue`

Author: pionl

docs/content/en/transformers.md

@@ -75,30 +75,28 @@ $transformer = new ClosureTransformer(function (mixed $value, string $key): ?str
 $md5 = $getValue->getString('key', [$transformer]);
 ```
 
-### ClosureArrayTransformer
+### ArrayTransformer
 
-> Cant be used only with get\*Array\* methods.
+> Can be used only with get\*Array\* methods.
 
 Transforms valid array using closure. Always return an array.
 
 ```php
-$transformer = new ClosureArrayTransformer(function (array $value, string $key): array {
+$transformer = new ArrayTransformer(function (array $value, string $key): array {
     return array_map(fn (string $value) => md5($value), $value);
 });
 
 $values = $getValue->getArray('key', [$transformer]);
 ```
 
-### ClosureArrayItemsTransformer
+### ArrayItemTransformer
 
-> Cant be used only with get\*Array\* methods.
+> Can be used only with get\*Array\* methods.
 
 Transforms **each value in an array** using closure.
 
 ```php
-$transformer = new ClosureArrayItemsTransformer( function (mixed $value, string $key): string {
-    $this->assertEquals('test', $key, 'Key does not match up');
-
+$transformer = new ArrayItemTransformer( function (mixed $value, string $key): string {
     if (is_string($value) !== null) {
         throw new ValidationFailedException($key, 'array value not a string');
     }
@@ -109,6 +107,22 @@ $transformer = new ClosureArrayItemsTransformer( function (mixed $value, string
 $values = $getValue->getArray('key', [$transformer]);
 ```
 
+### ArrayItemGetterTransformer
+
+> Can be used only with get\*Array\* methods. Throws NotAnArrayException if array value is not an array.
+
+Transforms an **array that contains array values** in a closure that receives wrapped array in GetValue.
+
+```php
+$transformer = new ArrayItemGetterTransformer( function (\Wrkflow\GetValue\GetValue $value, string $key): string {
+    return [
+        self::KeyValue => $value->getRequiredString(self::KeyValue),
+    ];
+});
+
+$values = $getValue->getArray('key', [$transformer]);
+```
+
 ## Customization
 
 You can create your own transformer by extending:

src/Actions/GetValidatedValueAction.php

@@ -6,7 +6,7 @@
 
 use Wrkflow\GetValue\Contracts\RuleContract;
 use Wrkflow\GetValue\Contracts\TransformerContract;
-use Wrkflow\GetValue\DataHolders\AbstractData;
+use Wrkflow\GetValue\GetValue;
 
 class GetValidatedValueAction
 {
@@ -19,15 +19,15 @@ public function __construct(
      * @param array<RuleContract>        $rules
      * @param array<TransformerContract> $transforms
      */
-    public function execute(AbstractData $data, string $key, array $rules, array $transforms): mixed
+    public function execute(GetValue $getValue, string $key, array $rules, array $transforms): mixed
     {
-        $value = $data->getValue($key);
+        $value = $getValue->data->getValue($key);
 
         $afterValidationTransforms = [];
 
         foreach ($transforms as $transform) {
             if ($rules === [] || $transform->beforeValidation(value: $value, key: $key)) {
-                $value = $transform->transform(value: $value, key: $key);
+                $value = $transform->transform(value: $value, key: $key, getValue: $getValue);
             } else {
                 $afterValidationTransforms[] = $transform;
             }
@@ -45,7 +45,7 @@ public function execute(AbstractData $data, string $key, array $rules, array $tr
         $this->validateAction->execute(rules: $rules, value: $value, key: $key);
 
         foreach ($afterValidationTransforms as $transform) {
-            $value = $transform->transform($value, $key);
+            $value = $transform->transform(value: $value, key: $key, getValue: $getValue);
         }
 
         return $value;

src/Contracts/TransformerArrayContract.php

@@ -4,7 +4,9 @@
 
 namespace Wrkflow\GetValue\Contracts;
 
+use Wrkflow\GetValue\GetValue;
+
 interface TransformerArrayContract extends TransformerContract
 {
-    public function transform(mixed $value, string $key): ?array;
+    public function transform(mixed $value, string $key, GetValue $getValue): ?array;
 }

src/Contracts/TransformerContract.php

@@ -4,9 +4,11 @@
 
 namespace Wrkflow\GetValue\Contracts;
 
+use Wrkflow\GetValue\GetValue;
+
 interface TransformerContract
 {
     public function beforeValidation(mixed $value, string $key): bool;
 
-    public function transform(mixed $value, string $key): mixed;
+    public function transform(mixed $value, string $key, GetValue $getValue): mixed;
 }

src/GetValue.php

@@ -320,6 +320,16 @@ public function getRequiredArrayGetter(string $key, ?array $transformers = null)
         return $this->makeInstance(new ArrayData($value));
     }
 
+    public function makeInstance(AbstractData $data): self
+    {
+        return new self(
+            data: $data,
+            transformerStrategy: $this->transformerStrategy,
+            exceptionBuilder: $this->exceptionBuilder,
+            getValidatedValueAction: $this->getValidatedValueAction
+        );
+    }
+
     /**
      * @param array<RuleContract>        $rules
      * @param RuleContract|null          $mainRule Adds given rule before all given rules.
@@ -335,16 +345,6 @@ protected function getValidatedValue(
             $rules = array_merge([$mainRule], $rules);
         }
 
-        return $this->getValidatedValueAction->execute($this->data, $key, $rules, $transformers);
-    }
-
-    protected function makeInstance(AbstractData $data): self
-    {
-        return new self(
-            data: $data,
-            transformerStrategy: $this->transformerStrategy,
-            exceptionBuilder: $this->exceptionBuilder,
-            getValidatedValueAction: $this->getValidatedValueAction
-        );
+        return $this->getValidatedValueAction->execute($this, $key, $rules, $transformers);
     }
 }

src/Transformers/ArrayItemGetterTransformer.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Transformers;
+
+use Closure;
+use Wrkflow\GetValue\Contracts\TransformerArrayContract;
+use Wrkflow\GetValue\DataHolders\ArrayData;
+use Wrkflow\GetValue\Exceptions\NotAnArrayException;
+use Wrkflow\GetValue\GetValue;
+
+/**
+ * Re-build an array with array items that are wrapped within GetValue wrapper
+ */
+class ArrayItemGetterTransformer implements TransformerArrayContract
+{
+    /**
+     * @param Closure(GetValue,string):array $onItem
+     * @param bool                             $beforeValidation
+     */
+    public function __construct(
+        private readonly Closure $onItem,
+        private readonly bool $beforeValidation = false
+    ) {
+    }
+
+    public function beforeValidation(mixed $value, string $key): bool
+    {
+        return $this->beforeValidation;
+    }
+
+    /**
+     * @param mixed|array<array>    $value
+     */
+    public function transform(mixed $value, string $key, GetValue $getValue): ?array
+    {
+        if (is_array($value) === false) {
+            return null;
+        }
+
+        $items = [];
+        foreach ($value as $index => $item) {
+            if (is_array($item) === false) {
+                throw new NotAnArrayException($key . ' at ' . $index);
+            }
+
+            $getItemValue = $getValue->makeInstance(new ArrayData($item));
+
+            $items[$index] = call_user_func_array($this->onItem, [$getItemValue, $key]);
+        }
+
+        return $items;
+    }
+}

src/Transformers/ClosureArrayItemsTransformer.php renamed to src/Transformers/ArrayItemTransformer.php

@@ -6,11 +6,12 @@
 
 use Closure;
 use Wrkflow\GetValue\Contracts\TransformerArrayContract;
+use Wrkflow\GetValue\GetValue;
 
 /**
  * Re-build the array with a closure for each item
  */
-class ClosureArrayItemsTransformer implements TransformerArrayContract
+class ArrayItemTransformer implements TransformerArrayContract
 {
     /**
      * @param Closure(mixed,string):(array|null) $onItem
@@ -27,7 +28,7 @@ public function beforeValidation(mixed $value, string $key): bool
         return $this->beforeValidation;
     }
 
-    public function transform(mixed $value, string $key): ?array
+    public function transform(mixed $value, string $key, GetValue $getValue): ?array
     {
         if (is_array($value) === false) {
             return null;

src/Transformers/ClosureArrayTransformer.php renamed to src/Transformers/ArrayTransformer.php

@@ -6,11 +6,12 @@
 
 use Closure;
 use Wrkflow\GetValue\Contracts\TransformerArrayContract;
+use Wrkflow\GetValue\GetValue;
 
 /**
  * Transforms the value using closure after validation has been done.
  */
-class ClosureArrayTransformer implements TransformerArrayContract
+class ArrayTransformer implements TransformerArrayContract
 {
     /**
      * @param Closure(array,string):array $closure
@@ -27,7 +28,7 @@ public function beforeValidation(mixed $value, string $key): bool
         return $this->beforeValidation;
     }
 
-    public function transform(mixed $value, string $key): ?array
+    public function transform(mixed $value, string $key, GetValue $getValue): ?array
     {
         if (is_array($value) === false) {
             return null;

src/Transformers/ClosureTransformer.php

@@ -6,6 +6,7 @@
 
 use Closure;
 use Wrkflow\GetValue\Contracts\TransformerContract;
+use Wrkflow\GetValue\GetValue;
 
 /**
  * Transforms the value using closure after validation has been done.
@@ -27,7 +28,7 @@ public function beforeValidation(mixed $value, string $key): bool
         return $this->beforeValidation;
     }
 
-    public function transform(mixed $value, string $key): mixed
+    public function transform(mixed $value, string $key, GetValue $getValue): mixed
     {
         return call_user_func_array($this->closure, [$value, $key]);
     }

src/Transformers/TransformToBool.php

@@ -5,6 +5,7 @@
 namespace Wrkflow\GetValue\Transformers;
 
 use Wrkflow\GetValue\Contracts\TransformerContract;
+use Wrkflow\GetValue\GetValue;
 
 /**
  * Transforms most used representations of boolean in string or number ('yes','no',1,0,'1','0','true','false') and
@@ -17,7 +18,7 @@ public function beforeValidation(mixed $value, string $key): bool
         return true;
     }
 
-    public function transform(mixed $value, string $key): mixed
+    public function transform(mixed $value, string $key, GetValue $getValue): mixed
     {
         // Ensure that value is boolean
         if ($value === 'true' || $value === true || $value === '1' || $value === 1 || $value === 'yes') {