Add transformers (with default opinied strategy).

By my opinion I've implemented default strategy based on my usage on all projects:

- **string** -> string is always trimmed and if it is empty then it will be transformed to null
- **bool** -> Converts most used representations of boolean in string or number ('yes','no',1,0,'1','0','true','false') and converts it to bool.

Breaking change: GetValue constructor arguments has changed.

Author: pionl

README.md

@@ -17,7 +17,10 @@ help with the documentation, new features, tests).
 
 - 🚀 Retrieve values from Array (JSON) / XML with correct return type
 - 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Ensures that desired value is in correct type (without additional loop validation. Validates always on get).
+- 🤹‍ Validation: Ensures that desired value is in correct type (without additional loop validation. Validation is always on
+  while calling get* method).
+- 🛠 Transformers: Ensures that values are in expected type (ensures that string is trimmed and empty string converted to
+  null, accepts bool as string, can be changed.)
 
 ```php
 $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([

composer.json

@@ -10,12 +10,12 @@
         }
     ],
     "require-dev": {
-        "phpstan/phpstan": "^1.6.3",
-        "phpstan/phpstan-deprecation-rules": "^1.0.0",
-        "phpstan/phpstan-phpunit": "^1.1.1",
-        "phpunit/phpunit": "^9.5.20",
-        "rector/rector": "^0.12.22",
-        "symplify/easy-coding-standard": "^10.2.2",
+        "phpstan/phpstan": "1.7.15",
+        "phpstan/phpstan-deprecation-rules": "1.0.0",
+        "phpstan/phpstan-phpunit": "1.1.1",
+        "phpunit/phpunit": "9.5.21",
+        "rector/rector": "0.13.6",
+        "symplify/easy-coding-standard": "11.0.5",
         "ext-simplexml": "*"
     },
     "scripts": {

docs/content/en/index.md

@@ -11,7 +11,10 @@ position: 1
 
 - 🚀 Retrieve values from Array (JSON) / XML with correct return type
 - 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Ensures that desired value is in correct type (without additional loop validation. Validates always on get).
+- 🤹‍ Validation: Ensures that desired value is in correct type (without additional loop validation. Validation is always on
+  while calling get* method).
+- 🛠 Transformers: Ensures that values are in expected type (ensures that string is trimmed and empty string converted to
+  null, accepts bool as string, can be changed.)
 
 ## Installation
 

docs/content/en/transformers.md

@@ -0,0 +1,94 @@
+---
+title: Transformers
+subtitle: 'Transform data to expected state'
+position: 3
+---
+
+## Features
+
+- All transformers can be combined.
+- All `get` methods has `transformers` argument
+- You are free to add more transformers to this package.
+
+## Strategy
+
+I've chosen most used combination while working with external services and created `DefaultTransformerStrategy`.
+
+You can disable or [change](#customization) this strategy while constructing `GetValue` instance.
+
+```php
+$data = new GetValue(data: $array, transformerStrategy: new NoTransformerStrategy());
+```
+
+## Transformers
+
+> Transformers parameter in get methods overrides transformers from strategy. 
+
+To disable default transformers set `transformers` argument to empty array.
+
+```php
+$transformer = new ClosureTransformer(function (mixed $value, string $key): ?string {
+        if ($value === null) {
+            return null;
+        }
+
+        return md5($value);
+    });
+$md5 = $getValue->getString('key', [$transformer]);
+```
+
+### ClosureTransformer
+
+Transforms the value using closure after validation has been done (can be changed with `$beforeValidation` argument).
+
+
+```php
+$getValue->getBool('key', [new \Wrkflow\GetValue\Transformers\TransformToBool()]);
+```
+
+### TransformToBool
+
+Transforms most used representations of boolean in string or number ('yes','no',1,0,'1','0','true','false') and converts
+it to bool **before** validation starts.
+
+```php
+$getValue->getBool('key', [new \Wrkflow\GetValue\Transformers\TransformToBool()]);
+```
+
+### TrimAndEmptyStringToNull
+
+> Used in DefaultTransformerStrategy
+
+Ensures that string is trimmed and transformed to null (if empty string is provided) **before** validation starts.
+
+```php
+$getValue->getString('key', [new \Wrkflow\GetValue\Transformers\TrimAndEmptyStringToNull()]);
+```
+
+### TrimString
+
+Ensures that string is trimmed **before** validation starts.
+
+```php
+// Get trimmed string (no '' to null transformation)
+$getValue->getString('key', [new \Wrkflow\GetValue\Transformers\TrimString()]);
+```
+
+## Customization
+
+You can create your own transformer by extending:
+
+- For array `Wrkflow\GetValue\Contracts\TransformerArrayContract`
+- Reset of values `Wrkflow\GetValue\Contracts\TransformerContract`
+
+Then implement `public function transform(mixed $value, string $key): mixed;`. Expect invalid value and make do not
+transform the value if it is invalid. Just return it. 
+
+Then implement `public function beforeValidation(mixed $value, string $key): bool;` which ensures that transformation
+is not done before validation. 
+
+Then change the strategy:
+
+```php
+$data = new GetValue(data: $array, transformerStrategy: new MyTransformerStrategy());
+```

docs/content/en/validation.md

@@ -7,7 +7,7 @@ position: 2
 ## Rules
 
 - All rules can be combined (all must be successful).
-- `get` methods has `rules` parameter. Check IDE autocomplete.
+- Except array* `get` methods has `rules` argument.
 - You can create your own rules by extending `Wrkflow\GetValue\Contracts\RuleContract`
 - You are free to add more rules to this package.
 

src/Actions/GetValidatedValueAction.php

@@ -4,36 +4,48 @@
 
 namespace Wrkflow\GetValue\Actions;
 
-use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
 use Wrkflow\GetValue\Contracts\RuleContract;
+use Wrkflow\GetValue\Contracts\TransformerContract;
 use Wrkflow\GetValue\DataHolders\AbstractData;
 
 class GetValidatedValueAction
 {
-    public function __construct(protected readonly ExceptionBuilderContract $exceptionBuilder)
-    {
+    public function __construct(
+        private readonly ValidateAction $validateAction
+    ) {
     }
 
     /**
-     * @param array<RuleContract> $rules
+     * @param array<RuleContract>        $rules
+     * @param array<TransformerContract> $transforms
      */
-    public function execute(string $key, AbstractData $data, array $rules): mixed
+    public function execute(AbstractData $data, string $key, array $rules, array $transforms): mixed
     {
         $value = $data->getValue($key);
 
+        $afterValidationTransforms = [];
+
+        foreach ($transforms as $transform) {
+            if ($rules === [] || $transform->beforeValidation(value: $value, key: $key)) {
+                $value = $transform->transform(value: $value, key: $key);
+            } else {
+                $afterValidationTransforms[] = $transform;
+            }
+        }
+
         if ($rules === []) {
             return $value;
         }
 
-        // Skip validation on null value
+        // Do not run validation on null
         if ($value === null) {
-            return $value;
+            return null;
         }
 
-        foreach ($rules as $rule) {
-            if ($rule->passes($value) === false) {
-                throw $this->exceptionBuilder->validationFailed($key, $rule::class);
-            }
+        $this->validateAction->execute(rules: $rules, value: $value, key: $key);
+
+        foreach ($afterValidationTransforms as $transform) {
+            $value = $transform->transform($value, $key);
         }
 
         return $value;

src/Actions/ValidateAction.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Actions;
+
+use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
+
+class ValidateAction
+{
+    public function __construct(
+        private readonly ExceptionBuilderContract $exceptionBuilder,
+    ) {
+    }
+
+    public function execute(array $rules, mixed $value, string $key): void
+    {
+        foreach ($rules as $rule) {
+            if ($rule->passes($value) === false) {
+                throw $this->exceptionBuilder->validationFailed($key, $rule::class);
+            }
+        }
+    }
+}

src/Contracts/TransformerArrayContract.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Contracts;
+
+interface TransformerArrayContract extends TransformerContract
+{
+    public function transform(mixed $value, string $key): array;
+}

src/Contracts/TransformerContract.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Contracts;
+
+interface TransformerContract
+{
+    public function beforeValidation(mixed $value, string $key): bool;
+
+    public function transform(mixed $value, string $key): mixed;
+}

src/Contracts/TransformerStrategy.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Contracts;
+
+interface TransformerStrategy
+{
+    /**
+     * @return array<TransformerContract>
+     */
+    public function string(): array;
+
+    /**
+     * @return array<TransformerContract>
+     */
+    public function int(): array;
+
+    /**
+     * @return array<TransformerContract>
+     */
+    public function bool(): array;
+
+    /**
+     * @return array<TransformerContract>
+     */
+    public function dateTime(): array;
+
+    /**
+     * @return array<TransformerContract>
+     */
+    public function float(): array;
+
+    /**
+     * @return array<TransformerArrayContract>
+     */
+    public function array(): array;
+}