Add value validation using rules #1

Author: pionl

README.md

@@ -17,7 +17,7 @@ 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
-- 🤹‍ Basic type without additional looping.
+- 🤹‍ Ensures that desired value is in correct type (without additional loop validation. Validates always on get).
 
 ```php
 $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([
@@ -27,7 +27,7 @@ $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayDa
         ['name' => 'test 2', 'tags' => ['test']],
     ],
 ]));
-$page = $data->getRequiredInt('page'); // Will throw MissingValueForKeyException
+$page = $data->getRequiredInt('page'); // Will throw MissingValueForKeyException if the `page` is not present
 $items = $data->getRequiredArray('items');
 
 foreach ($items as $item) {

composer.json

@@ -15,7 +15,8 @@
         "phpstan/phpstan-phpunit": "^1.1.1",
         "phpunit/phpunit": "^9.5.20",
         "rector/rector": "^0.12.22",
-        "symplify/easy-coding-standard": "^10.2.2"
+        "symplify/easy-coding-standard": "^10.2.2",
+        "ext-simplexml": "*"
     },
     "scripts": {
         "check": "composer lint && composer test",

docs/content/en/customization/custom-exceptions.md

@@ -28,6 +28,14 @@ class CustomExceptionBuilder extends
     {
         return new NotAnArrayException($key, $this->customLogContext);
     }
+
+    /**
+     * @param class-string<RuleContract> $ruleClassName
+     */
+    public function validationFailed(string $key, string $ruleClassName): Exception;
+    {
+        return new ValidationFailedException($key, $this->customLogContext);
+    }
 }
 ```
 

docs/content/en/index.md

@@ -11,7 +11,7 @@ position: 1
 
 - 🚀 Retrieve values from Array (JSON) / XML with correct return type
 - 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Basic type without additional looping.
+- 🤹‍ Ensures that desired value is in correct type (without additional loop validation. Validates always on get).
 
 ## Installation
 
@@ -33,7 +33,10 @@ Simple build **GetValue** class with **ArrayData** class that will expose the da
 ```php
 $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayData([
     'page' => 1, 
-    'items' => [['name' => 'test', 'tags' => null, 'label' => 'yes'], ['name' => 'test 2', 'tags' => ['test']]]
+    'items' => [
+        ['name' => 'test', 'tags' => null, 'label' => 'yes'], 
+        ['name' => 'test 2', 'tags' => ['test'],]
+    ],
 ]));
 ```
 
@@ -42,22 +45,28 @@ $data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\ArrayDa
 Simple build **GetValue** class with **XMLData** class that will expose the data.
 
 ```php
-$data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\XMLData(new SimpleXMLElement('<root><title>test</title><test attribute="test"/></root>')));
+$simpleXMLElement = new SimpleXMLElement('<root><title>test</title><test attribute="test"/></root>');
+$data = new \Wrkflow\GetValue\GetValue(new \Wrkflow\GetValue\DataHolders\XMLData($simpleXMLElement));
 ```
 
 ## Values
 
+> All values are validated within its type definition (int will be checked by IntegerRule, string by StringRule, etc).
+
 For getting values there are always 2 methods:
 
 - get nullable value
 - get required value
 
+You can additionally add validation rules (as second parameter) to ensure you will get correct value.
+Check [Validation documentation](/validation) for more.
+
 ### Int
 
 Get nullable int.
 
 ```php
-$value = $data->getInt('key');
+$value = $data->getInt('key', rules: [new \Wrkflow\GetValue\Rules\MinRule(0)]);
 ```
 
 Get required int value. Throws `MissingValueForKeyException` exception if missing.

docs/content/en/validation.md

@@ -0,0 +1,92 @@
+---
+title: Validation
+subtitle: 'Validate the value is not null.'
+position: 2
+---
+
+## Rules
+
+- All rules can be combined (all must be successful).
+- `get` methods has `rules` parameter. Check IDE autocomplete.
+- You can create your own rules by extending `Wrkflow\GetValue\Contracts\RuleContract`
+- You are free to add more rules to this package.
+
+### AlphaDashRule
+
+Checks if the string contains only digits/alphabet/-/_.
+
+### AlphaNumericRule
+
+Checks if the value is valid IP (using [FILTER_VALIDATE_IP](https://www.php.net/manual/en/filter.filters.flags.php))
+
+### ArrayRule
+
+Checks if the given value is an array. Not needed if using `getArray*` methods.
+
+### BetweenRule
+
+> Uses SizeRule
+
+Checks if the array|float|int|bool|string|null is within max/min (int/float).
+
+### BooleanRule
+
+Checks if the value is a boolean.
+
+### EmailRule
+
+Checks if the value is valid e-mail (
+using [FILTER_VALIDATE_EMAIL](https://www.php.net/manual/en/filter.filters.flags.php))
+
+### FloatRule
+
+Checks if the value is a float.
+
+### IntegerRule
+
+Checks if the value is a integer.
+
+### IpRule
+
+Checks if the value is valid IP (using [FILTER_VALIDATE_IP](https://www.php.net/manual/en/filter.filters.flags.php))
+
+### MaxRule
+
+> Uses SizeRule
+
+Checks if the array|float|int|bool|string|null is equal or greater than given int/float value.
+
+### MinRule
+
+Checks if the array|float|int|bool|string|null is equal or lower than given int/float value.
+
+### NumericRule
+
+Checks if the value is a numeric.
+
+### RegexRule
+
+Checks if value is valid against given regex.
+
+### SizeRule
+
+Checks if:
+
+- array - count of items equals to given value
+- float, int - equals to given value
+- bool - equals to given value 1 (true) or 0 (false)
+- string - length of string equals to given value
+
+### StringRule
+
+Checks if value is valid string.
+
+### UrlRule
+
+Checks if the value is valid URL (using [FILTER_VALIDATE_URL](https://www.php.net/manual/en/filter.filters.flags.php))
+
+## Notes
+
+- Rules code was extracted from [laurynasgadl/php-validator](https://github.com/laurynasgadl/php-validator) and PHPStan
+  8 ready. First I wanted to re-use existing package but did not find.
+- I'm thinking of that I will move rules to its own package for more reusability.

rector.php

@@ -3,13 +3,13 @@
 declare(strict_types=1);
 
 use Rector\CodingStyle\Rector\ClassConst\VarConstantCommentRector;
-use Rector\CodingStyle\Rector\ClassMethod\UnSpreadOperatorRector;
 use Rector\Config\RectorConfig;
 use Rector\Core\ValueObject\PhpVersion;
 use Rector\Set\ValueObject\LevelSetList;
 use Rector\Set\ValueObject\SetList;
 use Rector\Strict\Rector\AbstractFalsyScalarRuleFixerRector;
 use Rector\Strict\Rector\BooleanNot\BooleanInBooleanNotRuleFixerRector;
+use Rector\TypeDeclaration\Rector\ClassMethod\AddVoidReturnTypeWhereNoReturnRector;
 
 return static function (RectorConfig $config): void {
     $config->paths([__DIR__ . '/src', __DIR__ . '/tests']);
@@ -27,10 +27,10 @@
             AbstractFalsyScalarRuleFixerRector::TREAT_AS_NON_EMPTY => false,
         ]
     );
+    $config->ruleWithConfiguration(AddVoidReturnTypeWhereNoReturnRector::class, [
+        AddVoidReturnTypeWhereNoReturnRector::USE_PHPDOC => false,
+    ]);
 
     // SKIP laravel
-    $config->skip([
-        UnSpreadOperatorRector::class => [__DIR__ . '/src/Testing/Laravel/TestingApplication.php'],
-        VarConstantCommentRector::class,
-    ]);
+    $config->skip([VarConstantCommentRector::class]);
 };

src/Actions/GetValidatedValueAction.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Actions;
+
+use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
+use Wrkflow\GetValue\Contracts\RuleContract;
+use Wrkflow\GetValue\DataHolders\AbstractData;
+
+class GetValidatedValueAction
+{
+    public function __construct(protected readonly ExceptionBuilderContract $exceptionBuilder)
+    {
+    }
+
+    /**
+     * @param array<RuleContract> $rules
+     */
+    public function execute(string $key, AbstractData $data, array $rules): mixed
+    {
+        $value = $data->getValue($key);
+
+        if ($rules === []) {
+            return $value;
+        }
+
+        // Skip validation on null value
+        if ($value === null) {
+            return $value;
+        }
+
+        foreach ($rules as $rule) {
+            if ($rule->passes($value) === false) {
+                throw $this->exceptionBuilder->validationFailed($key, $rule::class);
+            }
+        }
+
+        return $value;
+    }
+}

src/Builders/ExceptionBuilder.php

@@ -9,6 +9,7 @@
 use Wrkflow\GetValue\Exceptions\ArrayIsEmptyException;
 use Wrkflow\GetValue\Exceptions\MissingValueForKeyException;
 use Wrkflow\GetValue\Exceptions\NotAnArrayException;
+use Wrkflow\GetValue\Exceptions\ValidationFailedException;
 
 class ExceptionBuilder implements ExceptionBuilderContract
 {
@@ -26,4 +27,12 @@ public function notAnArray(string $key): Exception
     {
         return new NotAnArrayException($key);
     }
+
+    public function validationFailed(string $key, string $ruleClassName): Exception
+    {
+        $classNameParts = explode('\\', $ruleClassName);
+        $shortClassName = end($classNameParts);
+
+        return new ValidationFailedException($key, $shortClassName . ' failed');
+    }
 }

src/Contracts/ExceptionBuilderContract.php

@@ -13,4 +13,9 @@ public function missingValue(string $key): Exception;
     public function arrayIsEmpty(string $key): Exception;
 
     public function notAnArray(string $key): Exception;
+
+    /**
+     * @param class-string<RuleContract> $ruleClassName
+     */
+    public function validationFailed(string $key, string $ruleClassName): Exception;
 }

src/Contracts/RuleContract.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Contracts;
+
+interface RuleContract
+{
+    public function passes(mixed $value): bool;
+}