Add filter for UUID values

README.md

@@ -152,6 +152,20 @@ $value = '{ "string": "value", "array": [1, 2, 3] }';
 assert($value === ['string' => 'value', 'array' => [1, 2, 3]]);
 ```
 
+#### UuidFilter::filter
+
+This filter verifies a given string is a valid universally unique identifier.
+
+The second parameter can be set to `true` to allow null values through without an error.
+
+The third parameter determines which UUID version the value will be validated against. By default, the filter will succeed if the values matches version 1, 2, 3, 4, 5, 6, or 7
+
+```php
+$value = '1a42403c-a29d-11ef-b864-0242ac120002';
+$filtered = \TraderInteractive\Filter\UuidFilter::filter($value);
+assert($value === $filtered);
+```
+
 #### XmlFilter::filter
 
 This filter ensures the given string is valid XML.

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,2,3,4,5,6,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/PhoneFilterTest.php

@@ -92,7 +92,7 @@ public function filterWithAllowNull()
      * @param mixed $value The value to filter.
      *
      * @test
-     * @covers ::__invoke
+     * @covers ::filter
      * @dataProvider provideFilterThrowsException
      */
     public function filterThrowsException($value)

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]);
+    }
+}