add new filter to filter to an enum

src/ToEnum.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\Filter;
+
+use Laminas\Filter\Exception\RuntimeException;
+use Laminas\Stdlib\ArrayUtils;
+use Traversable;
+use UnitEnum;
+
+use function is_array;
+use function is_int;
+use function is_string;
+use function is_subclass_of;
+
+/**
+ * @psalm-type Options = array{
+ *     enum: class-string<UnitEnum>,
+ * }
+ */
+final class ToEnum implements FilterInterface
+{
+    /**
+     * @var class-string<UnitEnum>|null
+     */
+    private ?string $enumClass = null;
+
+    /**
+     * @param class-string<UnitEnum>|Traversable|Options $enumOrOptions
+     */
+    public function __construct($enumOrOptions)
+    {
+        if ($enumOrOptions instanceof Traversable) {
+            $enumOrOptions = ArrayUtils::iteratorToArray($enumOrOptions);
+        }
+
+        if (
+            is_array($enumOrOptions) &&
+            isset($enumOrOptions['enum'])
+        ) {
+            $this->setEnum($enumOrOptions['enum']);
+
+            return;
+        }
+
+        if (is_string($enumOrOptions)) {
+            $this->setEnum($enumOrOptions);
+        }
+    }
+
+    /**
+     * @param class-string<UnitEnum> $enum
+     */
+    protected function setEnum(string $enum): self
+    {
+        $this->enumClass = $enum;
+
+        return $this;
+    }
+
+    /**
+     * Defined by Laminas\Filter\FilterInterface
+     *
+     * Returns an enum representation of $value or null
+     *
+     * @param  mixed $value
+     * @return UnitEnum|null
+     */
+    public function filter($value): ?UnitEnum
+    {
+        $enum = $this->enumClass;
+
+        if ($enum === null) {
+            throw new RuntimeException(
+                'enum class not set'
+            );
+        }
+
+        if (! is_string($value) && ! is_int($value)) {
+            return null;
+        }
+
+        if (is_subclass_of($enum, 'BackedEnum')) {
+            return $enum::tryFrom($value);
+        }
+
+        if (! is_string($value) || ! is_subclass_of($enum, 'UnitEnum')) {
+            return null;
+        }
+
+        foreach ($enum::cases() as $enumCase) {
+            if ($enumCase->name === $value) {
+                return $enumCase;
+            }
+        }
+
+        return null;
+    }
+}

test/TestAsset/TestIntBackedEnum.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Filter\TestAsset;
+
+enum TestIntBackedEnum: int
+{
+    case Foo = 1;
+    case Bar = 2;
+}

test/TestAsset/TestStringBackedEnum.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Filter\TestAsset;
+
+enum TestStringBackedEnum: string
+{
+    case Foo = 'foo';
+    case Bar = 'bar';
+}

test/TestAsset/TestUnitEnum.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Filter\TestAsset;
+
+enum TestUnitEnum
+{
+    case foo;
+    case bar;
+}

test/ToEnumTest.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaminasTest\Filter;
+
+use Laminas\Filter\Exception\RuntimeException;
+use Laminas\Filter\ToEnum;
+use LaminasTest\Filter\TestAsset\TestIntBackedEnum;
+use LaminasTest\Filter\TestAsset\TestStringBackedEnum;
+use LaminasTest\Filter\TestAsset\TestUnitEnum;
+use PHPUnit\Framework\TestCase;
+use UnitEnum;
+
+/**
+ * @requires PHP 8.1
+ */
+class ToEnumTest extends TestCase
+{
+    public function filterableValuesProvider(): array
+    {
+        return [
+            'unit enum'           => [TestUnitEnum::class, 'foo', TestUnitEnum::foo],
+            'backed string enum'  => [TestStringBackedEnum::class, 'foo', TestStringBackedEnum::Foo],
+            'backed integer enum' => [TestIntBackedEnum::class, 2, TestIntBackedEnum::Bar],
+        ];
+    }
+
+    /**
+     * @dataProvider filterableValuesProvider
+     * @param class-string<UnitEnum> $enumClass
+     */
+    public function testCanFilterToEnum(string $enumClass, string|int $value, UnitEnum $expectedFilteredValue): void
+    {
+        $filter = new ToEnum($enumClass);
+
+        self::assertSame($expectedFilteredValue, $filter->filter($value));
+    }
+
+    /**
+     * @dataProvider filterableValuesProvider
+     * @param class-string<UnitEnum> $enumClass
+     */
+    public function testCanFilterToEnumWithOptions(string $enumClass, string|int $value, UnitEnum $expectedFilteredValue): void
+    {
+        $filter = new ToEnum(['enum' => $enumClass]);
+
+        self::assertSame($expectedFilteredValue, $filter->filter($value));
+    }
+
+    public function unfilterableValuesProvider(): array
+    {
+        return [
+            'array'               => [TestUnitEnum::class, []],
+            'float'               => [TestUnitEnum::class, 1.1],
+            'bool'                => [TestUnitEnum::class, false],
+            'unit enum'           => [TestUnitEnum::class, 'baz'],
+            'backed string enum'  => [TestStringBackedEnum::class, 'baz'],
+            'backed integer enum' => [TestIntBackedEnum::class, 3],
+        ];
+    }
+
+    /**
+     * @dataProvider unfilterableValuesProvider
+     * @param class-string<UnitEnum> $enumClass
+     */
+    public function testFiltersToNull(string $enumClass, mixed $value): void
+    {
+        $filter = new ToEnum($enumClass);
+
+        self::assertNull($filter->filter($value));
+    }
+
+    public function testThrowsExceptionIfEnumNotSet(): void
+    {
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('enum class not set');
+
+        $filter = new ToEnum([]);
+
+        $filter->filter('foo');
+    }
+}