Add UuidFilter

Author: chadicus

src/Filter/UuidFilter.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace TraderInteractive\Filter;
+
+use InvalidArgumentException;
+use TraderInteractive\Exceptions\FilterException;
+
+final class UuidFilter
+{
+    /**
+     * @var string
+     */
+    const FILTER_ALIAS = 'uuid';
+
+    /**
+     * @var string
+     */
+    const UUID_PATTERN_FORMAT = '^[0-9A-F]{8}-[0-9A-F]{4}-[%d][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$';
+
+    /**
+     * @var string
+     */
+    const FILTER_ERROR_FORMAT = "Value '%s' is not a valid UUID. Versions checked (%s)";
+
+    /**
+     * @var array
+     * @internal
+     */
+    const VALID_UUID_VERSIONS = [1,4,7];
+
+
+    /**
+     * Filters a given string values to a valid UUID
+     *
+     * @param string|null $value     The value to be filtered.
+     * @param bool        $allowNull Flag to allow value to be null.
+     * @param array       $versions  List of specific UUID version to validate against.
+     *
+     * @return string|null
+     *
+     * @throws FilterException Thrown if value cannot be filtered as an UUID.
+     */
+    public static function filter(
+        string $value = null,
+        bool $allowNull = false,
+        array $versions = self::VALID_UUID_VERSIONS
+    ) {
+        if (self::valueIsNullAndValid($allowNull, $value)) {
+            return null;
+        }
+
+        self::validateVersions($versions);
+        foreach ($versions as $version) {
+            $pattern = sprintf(self::UUID_PATTERN_FORMAT, $version);
+            if (preg_match("/{$pattern}/i", $value)) {
+                return $value;
+            }
+        }
+
+        throw new FilterException(
+            sprintf(
+                self::FILTER_ERROR_FORMAT,
+                $value,
+                implode(', ', $versions)
+            )
+        );
+    }
+
+    private static function valueIsNullAndValid(bool $allowNull, string $value = null): bool
+    {
+        if ($allowNull === false && $value === null) {
+            throw new FilterException('Value failed filtering, $allowNull is set to false');
+        }
+
+        return $allowNull === true && $value === null;
+    }
+
+    private static function validateVersions(array $versions)
+    {
+        foreach ($versions as $version) {
+            if (!in_array($version, self::VALID_UUID_VERSIONS)) {
+                throw new InvalidArgumentException("Filter does not support UUID v{$version}");
+            }
+        }
+    }
+}

tests/Filter/UuidFilterTest.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Filter;
+
+use InvalidArgumentException;
+use TraderInteractive\Exceptions\FilterException;
+use TraderInteractive\Filter\UuidFilter;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversDefaultClass \TraderInteractive\Filter\UuidFilter
+ * @covers ::<private>
+ */
+final class UuidFilterTest extends TestCase
+{
+    /**
+     * @var string
+     * @internal
+     */
+    const UUID_V1 = '1a42403c-a29d-11ef-b864-0242ac120002';
+
+    /**
+     * @var string
+     * @internal
+     */
+    const UUID_V4 = 'cc468b36-0b9d-4c93-b8e9-d5e949331ffb';
+
+    /**
+     * @var string
+     * @internal
+     */
+    const UUID_V7 = '01932b4a-af2b-7093-af59-2fb2044d13d8';
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterUuidV1()
+    {
+        $this->assertSame(self::UUID_V1, UuidFilter::filter(self::UUID_V1));
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterUuidV4()
+    {
+        $this->assertSame(self::UUID_V4, UuidFilter::filter(self::UUID_V4));
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterUuidV7()
+    {
+        $this->assertSame(self::UUID_V7, UuidFilter::filter(self::UUID_V7));
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterNullAllowedNullIsTrue()
+    {
+        $this->assertNull(UuidFilter::filter(null, true));
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterNullAllowedNullIsFalse()
+    {
+        $this->expectException(FilterException::class);
+        UuidFilter::filter(null, false);
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterWithInvalidVersionSpecified()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Filter does not support UUID v0');
+        UuidFilter::filter(self::UUID_V7, false, [0]);
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterValueDoesNotMatchGivenVersions()
+    {
+        $this->expectException(FilterException::class);
+        $this->expectExceptionMessage(
+            sprintf(
+                UuidFilter::FILTER_ERROR_FORMAT,
+                self::UUID_V4,
+                implode(', ', [1,7])
+            )
+        );
+        UuidFilter::filter(self::UUID_V4, false, [1,7]);
+    }
+}