Add enum support (EnumRule + getEnum/getRequiredEnum)

Author: pionl

docs/content/en/index.md

@@ -12,7 +12,8 @@ position: 1
 
 - 🚀 Retrieve values from Array (JSON) / XML with correct return type
 - 🏆 Makes PHPStan / IDE happy due the return types
-- 🤹‍ Validation: Ensures that desired value is in correct type (without additional loop validation. Validation is always on
+- 🤹‍ 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.)
@@ -115,7 +116,8 @@ $value = $data->getRequiredBool('key');
 
 ### String
 
-> Throws `ValidationFailedException` if value is not string (only on non-null values).
+> Throws `ValidationFailedException` if value is not string (only on non-null values). In default strategy empty string
+> is treated as null.
 
 Get nullable string value.
 
@@ -129,6 +131,23 @@ Get required string value. Throws `MissingValueForKeyException` exception if mis
 $value = $data->getRequiredString('key');
 ```
 
+### Enum
+
+> Throws `ValidationFailedException` if value is not in the enum. In default strategy empty string
+> is treated as null. Works only on string/int enums.
+
+Get nullable enum value from a string/int.
+
+```php
+$value = $data->getEnum('key', MyEnum::class);
+```
+
+Get required enum value. Throws `MissingValueForKeyException` exception if missing.
+
+```php
+$value = $data->getRequiredEnum('key', MyEnum::class);
+```
+
 ### Date time
 
 > Throws `ValidationFailedException` if value is not string (only on non-null values).

docs/content/en/validation.md

@@ -74,6 +74,14 @@ Using [FILTER_VALIDATE_EMAIL](https://www.php.net/manual/en/filter.filters.flags
 $getValue->getString('test', rules: [new \Wrkflow\GetValue\Rules\EmailRule()]);
 ```
 
+### EnumRule
+
+Checks if given value is in enum. With default strategy empty string is treated as null (not set).
+
+```php
+$getValue->getString('test', rules: [new \Wrkflow\GetValue\Rules\EnumRule(MyEnum::class)]);
+```
+
 ### FloatRule
 
 > Not needed if using `getFloat*` methods.

src/GetValue.php

@@ -4,9 +4,12 @@
 
 namespace Wrkflow\GetValue;
 
+use BackedEnum;
 use DateTime;
 use DateTimeImmutable;
 use DateTimeInterface;
+use TypeError;
+use UnitEnum;
 use Wrkflow\GetValue\Actions\GetValidatedValueAction;
 use Wrkflow\GetValue\Actions\ValidateAction;
 use Wrkflow\GetValue\Builders\ExceptionBuilder;
@@ -18,6 +21,7 @@
 use Wrkflow\GetValue\DataHolders\AbstractData;
 use Wrkflow\GetValue\DataHolders\ArrayData;
 use Wrkflow\GetValue\Rules\BooleanRule;
+use Wrkflow\GetValue\Rules\EnumRule;
 use Wrkflow\GetValue\Rules\NumericRule;
 use Wrkflow\GetValue\Rules\StringRule;
 use Wrkflow\GetValue\Strategies\DefaultTransformerStrategy;
@@ -128,7 +132,7 @@ public function getBool(string $key, array $rules = [], ?array $transformers = n
     }
 
     /**
-     * @param array<RuleContract>        $rules
+     * @param array<RuleContract>             $rules
      * @param array<TransformerContract>|null $transformers
      */
     public function getRequiredBool(string $key, array $rules = [], ?array $transformers = null): bool
@@ -143,7 +147,7 @@ public function getRequiredBool(string $key, array $rules = [], ?array $transfor
     }
 
     /**
-     * @param array<RuleContract>        $rules
+     * @param array<RuleContract>             $rules
      * @param array<TransformerContract>|null $transformers
      */
     public function getString(string $key, array $rules = [], ?array $transformers = null): ?string
@@ -163,7 +167,7 @@ public function getString(string $key, array $rules = [], ?array $transformers =
     }
 
     /**
-     * @param array<RuleContract>        $rules
+     * @param array<RuleContract>             $rules
      * @param array<TransformerContract>|null $transformers
      */
     public function getRequiredString(string $key, array $rules = [], ?array $transformers = null): string
@@ -178,7 +182,48 @@ public function getRequiredString(string $key, array $rules = [], ?array $transf
     }
 
     /**
-     * @param array<RuleContract>        $rules
+     * @template TEnum of BackedEnum
+     * @param class-string<TEnum> $enum
+     * @param array<RuleContract>             $rules
+     * @param array<TransformerContract>|null $transformers
+     * @return TEnum|null
+     */
+    public function getEnum(string $key, string $enum, array $rules = [], ?array $transformers = null): ?UnitEnum
+    {
+        $value = $this->getString(key: $key, rules: $rules + [new EnumRule($enum)], transformers: $transformers);
+
+        if ($value === null) {
+            return null;
+        }
+
+        //At this moment I've not found a way to detect int/string enum
+        try {
+            return $enum::from($value);
+        } catch (TypeError) {
+            return $enum::from((int) $value);
+        }
+    }
+
+    /**
+     * @template TEnum of BackedEnum
+     * @param class-string<TEnum> $enum
+     * @param array<RuleContract>             $rules
+     * @param array<TransformerContract>|null $transformers
+     * @return TEnum
+     */
+    public function getRequiredEnum(string $key, string $enum, array $rules = [], ?array $transformers = null): UnitEnum
+    {
+        $value = $this->getEnum(key: $key, enum: $enum, rules: $rules, transformers: $transformers);
+
+        if ($value instanceof BackedEnum === false) {
+            throw  $this->exceptionBuilder->missingValue($key);
+        }
+
+        return $value;
+    }
+
+    /**
+     * @param array<RuleContract>             $rules
      * @param array<TransformerContract>|null $transformers
      *
      * @return DateTime|DateTimeImmutable|null
@@ -200,7 +245,7 @@ public function getDateTime(string $key, array $rules = [], ?array $transformers
     }
 
     /**
-     * @param array<RuleContract>        $rules
+     * @param array<RuleContract>             $rules
      * @param array<TransformerContract>|null $transformers
      *
      * @return DateTime|DateTimeImmutable

src/Rules/EnumRule.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValue\Rules;
+
+use BackedEnum;
+use LogicException;
+use TypeError;
+use Wrkflow\GetValue\Contracts\RuleContract;
+
+class EnumRule implements RuleContract
+{
+    /**
+     * @param class-string<BackedEnum> $enum
+     */
+    public function __construct(private readonly string $enum)
+    {
+    }
+
+    public function passes(mixed $value): bool
+    {
+        if (is_int($value) === false && is_string($value) === false) {
+            return false;
+        }
+
+        if (enum_exists($this->enum) === false) {
+            throw new LogicException(sprintf('Provided enum <%s> is not an enum or it does not exists.', $this->enum));
+        }
+
+        if (method_exists($this->enum, 'tryFrom') === false) {
+            throw new LogicException(sprintf('Provided enum <%s> is not supported. Use string/int enum.', $this->enum));
+        }
+
+        // If we are using int enum, and we will receive "string" it will throw TypeError.
+        try {
+            return $this->enum::tryFrom($value) !== null;
+        } catch (TypeError) {
+            return false;
+        }
+    }
+}

tests/AbstractArrayTestCase.php

@@ -7,6 +7,8 @@
 use PHPUnit\Framework\TestCase;
 use Wrkflow\GetValue\DataHolders\ArrayData;
 use Wrkflow\GetValue\GetValue;
+use Wrkflow\GetValueTests\Enums\EnumInt;
+use Wrkflow\GetValueTests\Enums\EnumString;
 
 abstract class AbstractArrayTestCase extends TestCase
 {
@@ -46,6 +48,10 @@ abstract class AbstractArrayTestCase extends TestCase
 
     final protected const KeyIsActiveInFalse = 'is_active_false';
 
+    final protected const KeyEnum = 'enum';
+
+    final protected const KeyEnumInt = 'enum_int';
+
     protected GetValue $data;
 
     protected ArrayData $arrayData;
@@ -79,6 +85,8 @@ protected function setUp(): void
                 self::KeyIsActiveInFalse => null,
                 self::KeyAmount => null,
                 self::KeyUpdatedAt => null,
+                self::KeyEnum => null,
+                self::KeyEnumInt => null,
             ],
             self::KeyEmpty => [
                 self::KeyTags => [],
@@ -88,6 +96,8 @@ protected function setUp(): void
                 self::KeyIsActiveInFalse => '',
                 self::KeyAmount => '',
                 self::KeyUpdatedAt => '',
+                self::KeyEnum => '',
+                self::KeyEnumInt => '',
             ],
             self::KeyValid => [
                 self::KeyTags => ['test'],
@@ -97,6 +107,8 @@ protected function setUp(): void
                 self::KeyIsActiveInFalse => false,
                 self::KeyAmount => 10.2,
                 self::KeyUpdatedAt => '2022-02-02 23:22:21',
+                self::KeyEnum => EnumString::Test->value,
+                self::KeyEnumInt => EnumInt::Test->value,
             ],
             self::KeyInvalid => [
                 self::KeyTags => 'test',
@@ -106,6 +118,8 @@ protected function setUp(): void
                 self::KeyIsActiveInFalse => 'not_bool',
                 self::KeyAmount => 'not_float',
                 self::KeyUpdatedAt => 'not_date_time',
+                self::KeyEnum => 0,
+                self::KeyEnumInt => 's',
             ],
             self::KeyMissingValue => ['force-non-empty'],
         ]);

tests/Enums/EnumInt.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Enums;
+
+enum EnumInt: int
+{
+    case Test = 1;
+    case Test2 = 2;
+}

tests/Enums/EnumOther.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Enums;
+
+enum EnumOther
+{
+    case Test;
+}

tests/Enums/EnumString.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Enums;
+
+enum EnumString: string
+{
+    case Test = 'test';
+    case Test2 = 'test-2';
+}