Allow Array*Transformers in all get* methods and ignore null values

- Ignore null values while re-building (ArrayItemTransformer, ArrayItemGetterTransformer) an array
- Breaking change: TransformerArrayContract removed

Author: pionl

docs/content/en/transformers.md

@@ -138,6 +138,30 @@ $transformer = new ArrayTransformer(function (array $value, string $key): array
 });
 
 $values = $data->getArray('key', transformers: [$transformer]);
+// Result: ['2231d0878e1f14976c498ad49de37ef6', 'edc23e3209134c89922592669e09cb65']
+```
+
+If you want to use this transformer with getString and other non-array method then you need to run the
+transformer before validation by setting `beforeValidation: true`.
+
+
+```php
+use Wrkflow\GetValue\GetValue;
+use Wrkflow\GetValue\DataHolders\ArrayData;
+use Wrkflow\GetValue\Transformers\ArrayTransformer;
+
+$data = new GetValue(new ArrayData([
+   'key' => ['Marco', 'Polo']
+]));
+
+$transformer = new ArrayTransformer(
+   closure: fn (array $value, string $key): string => implode(' ', $value),
+   beforeValidation: true
+);
+
+$name = $data->getString('key', transformers: [$transformer]);
+$this->assertEquals('Marco Polo', $name);
+// Result: Marco Polo
 ```
 
 ### ArrayItemTransformer
@@ -153,80 +177,88 @@ use Wrkflow\GetValue\Transformers\ArrayItemTransformer;
 use Wrkflow\GetValue\Exceptions\ValidationFailedException;
 
 $data = new GetValue(new ArrayData([
-    'key' => ['Marco', 'Polo']
+   'names' => [['Marco', 'Polo'], ['Way', 'Point'], []]
 ]));
 $transformer = new ArrayItemTransformer( function (mixed $value, string $key): string {
-    if (is_string($value) !== null) {
-        throw new ValidationFailedException($key, 'array value not a string');
-    }
-
-    return md5($value);
+   if (is_array($value) !== true) {
+       throw new ValidationFailedException($key, 'expecting an array');
+   }
+   
+   if ($value === []) {
+        return null;
+   }
+
+   return implode(' ', $value);
 });
 
-$values = $data->getArray('key', transformers: [$transformer]);
+$values = $data->getArray('names', transformers: [$transformer]);
+// Result: ['Marco Polo', 'Way Point']
 ```
 
-### 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.
+If you return `null` in your closure then value is not added to result array. Use `ignoreNullResult: false` in constructor.
 
 ```php
 use Wrkflow\GetValue\GetValue;
 use Wrkflow\GetValue\DataHolders\ArrayData;
-use Wrkflow\GetValue\Transformers\ArrayItemGetterTransformer;
+use Wrkflow\GetValue\Transformers\ArrayItemTransformer;
+use Wrkflow\GetValue\Exceptions\ValidationFailedException;
 
 $data = new GetValue(new ArrayData([
-    'key' => [['test' => 'Marco'], ['test' => 'Polo']]
+   'names' => ['Marco Polo', 'Way Point', ''],
 ]));
-$transformer = new ArrayItemGetterTransformer( function (GetValue $value, string $key): string {
-    return [
-        'test' => $value->getRequiredString('test'),
-    ];
-});
+$transformer = new ArrayItemTransformer(function (mixed $value, string $key): ?array {
+   if (is_string($value) === false) {
+       throw new ValidationFailedException($key, 'expecting string');
+   }
 
-$values = $data->getArray('key', transformers: [$transformer]);
+   if ($value === '') {
+       return null;
+   }
+
+   return explode(' ', $value);
+}, ignoreNullResult: false);
+
+$values = $data->getArray('names', transformers: [$transformer]);
+// Result: [['Marco', 'Polo'], ['Way', 'Point'], null]
 ```
 
 ### ArrayItemGetterTransformer
 
-> Can be used only with get\*Array\* methods.
+> Can be used only with get\*Array\* methods. Throws NotAnArrayException if array value is not an array.
 
-Transforms an **array** in a closure that receives wrapped array in GetValue.
+Transforms an **array that contains array values** in a closure that receives wrapped array in GetValue.
 
 ```php
 use Wrkflow\GetValue\GetValue;
 use Wrkflow\GetValue\DataHolders\ArrayData;
-use Wrkflow\GetValue\Transformers\ArrayGetterTransformer;
+use Wrkflow\GetValue\Transformers\ArrayItemGetterTransformer;
 
 $data = new GetValue(new ArrayData([
-    'key' => ['test' => 'Value!']
+   'names' => [['name' => 'Marco', 'surname' => 'Polo'], ['name' => 'Martin', 'surname' => 'Way']]
 ]));
-$transformer = new ArrayGetterTransformer(function (GetValue $value, string $key): string {
-    return [
-        'test' => $value->getRequiredString('test'),
-    ];
+
+$transformer = new ArrayItemGetterTransformer(function (GetValue $value, string $key): string {
+   return $value->getRequiredString('name') . ' '.$value->getRequiredString('surname');
 });
 
-$values = $data->getArray('key', transformers: [$transformer]);
+$values = $data->getArray('names', transformers: [$transformer]);
+// Result: ['Marco Polo', 'Martin Way']
 ```
 
-## Customization
-
-You can create your own transformer by extending:
+If you return `null` in your closure then value is not added to result array. Use `ignoreNullResult: false` in same way
+as in [ArrayItemTransformer](#arrayitemtransformer)`.
 
-- For array `Wrkflow\GetValue\Contracts\TransformerArrayContract`
-- Rest of the value types use `Wrkflow\GetValue\Contracts\TransformerContract`
-- `$key` contains full path key from the root data. Array notation is converted to dot notation.
-
-Then implement `public function transform(mixed $value, string $key): mixed;`. Expect that you can receive an invalid
-value. Return original `$value` if transformation can't be done.
+## Customization
 
-Then implement `public function beforeValidation(mixed $value, string $key): bool;` which ensures that transformation
-is not done before validation.
+You can create your own transformer by extending `Wrkflow\GetValue\Contracts\TransformerContract` class:
 
-Then change the strategy:
+1. Then implement `public function transform(mixed $value, string $key): mixed;`. Expect that you can receive an invalid
+   value. Return original `$value` if transformation can't be done.
+2. Then implement `public function beforeValidation(mixed $value, string $key): bool;` which tells if we can transform
+   the value after or before validation.
+    - Use before validation for transforming value to a type that `get` method expects.
+3. You can use `$key` which contains full path key from the root data. Array notation is converted to dot notation.
+4. Then change the strategy:
 
 ```php
 use Wrkflow\GetValue\GetValue;

src/Contracts/TransformerArrayContract.php

@@ -32,7 +32,7 @@ public function dateTime(): array;
     public function float(): array;
 
     /**
-     * @return array<TransformerArrayContract>
+     * @return array<TransformerContract>
      */
     public function array(): array;
 }

src/Contracts/TransformerStrategy.php

@@ -15,7 +15,6 @@
 use Wrkflow\GetValue\Builders\ExceptionBuilder;
 use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
 use Wrkflow\GetValue\Contracts\RuleContract;
-use Wrkflow\GetValue\Contracts\TransformerArrayContract;
 use Wrkflow\GetValue\Contracts\TransformerContract;
 use Wrkflow\GetValue\Contracts\TransformerStrategy;
 use Wrkflow\GetValue\DataHolders\AbstractData;
@@ -276,7 +275,7 @@ public function getRequiredDateTime(
     /**
      * Ensures that always an array will be returned (if missing in $data or if null).
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      */
     public function getArray(string|array $key, ?array $transformers = null): array
     {
@@ -299,7 +298,7 @@ public function getArray(string|array $key, ?array $transformers = null): array
     /**
      * Ensures that always an array will be returned (if missing in $data or if null).
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      */
     public function getNullableArray(string|array $key, ?array $transformers = null): ?array
     {
@@ -322,7 +321,7 @@ public function getNullableArray(string|array $key, ?array $transformers = null)
     /**
      * Checks if the array is in the data set with non-empty array
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      *
      * @phpstan-return non-empty-array
      */
@@ -340,7 +339,7 @@ public function getRequiredArray(string|array $key, ?array $transformers = null)
     /**
      * Get always `GetValue` instance even if provided data is missing or if null.
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      */
     public function getArrayGetter(string|array $key, ?array $transformers = null): self
     {
@@ -352,7 +351,7 @@ public function getArrayGetter(string|array $key, ?array $transformers = null):
     /**
      * Try to get nullable array from data and wrap it in `GetValue` instance.
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      */
     public function getNullableArrayGetter(string|array $key, ?array $transformers = null): ?self
     {
@@ -368,7 +367,7 @@ public function getNullableArrayGetter(string|array $key, ?array $transformers =
     /**
      * Checks if the array is in the data set with non-empty array
      *
-     * @param array<TransformerArrayContract>|null $transformers
+     * @param array<TransformerContract>|null $transformers
      */
     public function getRequiredArrayGetter(string|array $key, ?array $transformers = null): self
     {

src/GetValue.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Transformers;
+
+use Wrkflow\GetValue\Contracts\TransformerContract;
+use Wrkflow\GetValue\GetValue;
+
+abstract class AbstractArrayItemTransformer implements TransformerContract
+{
+    public function transform(mixed $value, string $key, GetValue $getValue): mixed
+    {
+        if (is_array($value) === false) {
+            return null;
+        }
+
+        $isAssociative = true;
+        $items = [];
+        $previousIndex = null;
+        foreach ($value as $index => $item) {
+            $result = $this->transformItem($item, $key, $index, $getValue);
+
+            if (is_int($index) && $isAssociative) {
+                if ($previousIndex !== null) {
+                    $isAssociative = $previousIndex + 1 === $index;
+                }
+
+                $previousIndex = $index;
+            } else {
+                $isAssociative = false;
+            }
+
+            if ($this->ignoreNullResult() && $result === null) {
+                continue;
+            }
+
+            $items[$index] = $result;
+        }
+
+        return $isAssociative ? array_values($items) : $items;
+    }
+
+    abstract protected function transformItem(mixed $item, string $key, string|int $index, GetValue $getValue): mixed;
+
+    abstract protected function ignoreNullResult(): bool;
+}

src/Transformers/AbstractArrayItemTransformer.php

@@ -5,18 +5,18 @@
 namespace Wrkflow\GetValue\Transformers;
 
 use Closure;
-use Wrkflow\GetValue\Contracts\TransformerArrayContract;
+use Wrkflow\GetValue\Contracts\TransformerContract;
 use Wrkflow\GetValue\DataHolders\ArrayData;
 use Wrkflow\GetValue\GetValue;
 
 /**
  * Transforms the value using closure after validation has been done.
  */
-class ArrayGetterTransformer implements TransformerArrayContract
+class ArrayGetterTransformer implements TransformerContract
 {
     /**
-     * @param Closure(GetValue,string):array $closure
-     * @param bool    $beforeValidation
+     * @param Closure(GetValue,string):mixed $closure
+     * @param bool                           $beforeValidation
      */
     public function __construct(
         private readonly Closure $closure,
@@ -29,7 +29,7 @@ public function beforeValidation(mixed $value, string $key): bool
         return $this->beforeValidation;
     }
 
-    public function transform(mixed $value, string $key, GetValue $getValue): ?array
+    public function transform(mixed $value, string $key, GetValue $getValue): mixed
     {
         if (is_array($value) === false) {
             return null;

src/Transformers/ArrayGetterTransformer.php

@@ -5,23 +5,25 @@
 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
+class ArrayItemGetterTransformer extends AbstractArrayItemTransformer
 {
     /**
-     * @param Closure(GetValue,string):array $onItem
-     * @param bool                             $beforeValidation
+     * @param Closure(GetValue,string):mixed $onItem
+     * @param bool                           $beforeValidation
+     * @param bool                           $ignoreNullResult Allows to prevent adding null value to array when
+     *                                                         rebuilding an array.
      */
     public function __construct(
         private readonly Closure $onItem,
-        private readonly bool $beforeValidation = false
+        private readonly bool $beforeValidation = false,
+        private readonly bool $ignoreNullResult = true,
     ) {
     }
 
@@ -30,26 +32,19 @@ 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
+    protected function transformItem(mixed $item, string $key, string|int $index, GetValue $getValue): mixed
     {
-        if (is_array($value) === false) {
-            return null;
+        if (is_array($item) === false) {
+            throw new NotAnArrayException($key . ' at ' . $index);
         }
 
-        $items = [];
-        foreach ($value as $index => $item) {
-            if (is_array($item) === false) {
-                throw new NotAnArrayException($key . ' at ' . $index);
-            }
-
-            $getItemValue = $getValue->makeInstance(new ArrayData($item, $getValue->data->getKey($key)));
+        $getItemValue = $getValue->makeInstance(new ArrayData($item, $getValue->data->getKey($key)));
 
-            $items[$index] = call_user_func_array($this->onItem, [$getItemValue, $key]);
-        }
+        return call_user_func_array($this->onItem, [$getItemValue, $key]);
+    }
 
-        return $items;
+    protected function ignoreNullResult(): bool
+    {
+        return $this->ignoreNullResult;
     }
 }