Allow nil UUIDs

Author: chadicus

src/Filter/UuidFilter.php

@@ -22,6 +22,11 @@ final class UuidFilter
      */
     const FILTER_ERROR_FORMAT = "Value '%s' is not a valid UUID. Versions checked (%s)";
 
+    /**
+     * @var string
+     */
+    const NIL_NOT_ALLOWED_ERROR_FORMAT = "Value '%s' is nil uuid, but nil values are not allowed.";
+
     /**
      * @var string
      */
@@ -32,6 +37,11 @@ final class UuidFilter
      */
     const UNSUPPORTED_VERSION_ERROR_FORMAT = 'Filter does not support UUID v%d';
 
+    /**
+     * @var string
+     */
+    const NIL_UUID = '00000000-0000-0000-0000-000000000000';
+
     /**
      * @var array
      * @internal
@@ -44,6 +54,7 @@ final class UuidFilter
      *
      * @param string|null $value     The value to be filtered.
      * @param bool        $allowNull Flag to allow value to be null.
+     * @param bool        $allowNil  Flag to allow value to be a NIL UUID.
      * @param array       $versions  List of specific UUID version to validate against.
      *
      * @return string|null
@@ -53,12 +64,17 @@ final class UuidFilter
     public static function filter(
         string $value = null,
         bool $allowNull = false,
+        bool $allowNil = false,
         array $versions = self::VALID_UUID_VERSIONS
     ) {
         if (self::valueIsNullAndValid($allowNull, $value)) {
             return null;
         }
 
+        if (self::valueIsNilAndValid($allowNil, $value)) {
+            return self::NIL_UUID;
+        }
+
         self::validateVersions($versions);
         foreach ($versions as $version) {
             $pattern = sprintf(self::UUID_PATTERN_FORMAT, $version);
@@ -85,6 +101,15 @@ private static function valueIsNullAndValid(bool $allowNull, string $value = nul
         return $allowNull === true && $value === null;
     }
 
+    private static function valueIsNilAndValid(bool $allowNil, string $value = null): bool
+    {
+        if ($allowNil === false && $value === self::NIL_UUID) {
+            throw new FilterException(sprintf(self::NIL_NOT_ALLOWED_ERROR_FORMAT, $value));
+        }
+
+        return $allowNil === true && $value === self::NIL_UUID;
+    }
+
     private static function validateVersions(array $versions)
     {
         foreach ($versions as $version) {

tests/Filter/UuidFilterTest.php

@@ -85,7 +85,7 @@ public function filterWithInvalidVersionSpecified()
     {
         $this->expectException(InvalidArgumentException::class);
         $this->expectExceptionMessage(sprintf(UuidFilter::UNSUPPORTED_VERSION_ERROR_FORMAT, 0));
-        UuidFilter::filter(self::UUID_V7, false, [0]);
+        UuidFilter::filter(self::UUID_V7, false, false, [0]);
     }
 
     /**
@@ -102,6 +102,28 @@ public function filterValueDoesNotMatchGivenVersions()
                 implode(', ', [1,7])
             )
         );
-        UuidFilter::filter(self::UUID_V4, false, [1,7]);
+        UuidFilter::filter(self::UUID_V4, false, false, [1,7]);
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterNilUuid()
+    {
+        $value = UuidFilter::NIL_UUID;
+        $this->assertSame($value, UuidFilter::filter($value, false, true));
+    }
+
+    /**
+     * @test
+     * @covers ::filter
+     */
+    public function filterNilUuidNilNotAllowed()
+    {
+        $value = UuidFilter::NIL_UUID;
+        $this->expectException(FilterException::class);
+        $this->expectExceptionMessage(sprintf(UuidFilter::NIL_NOT_ALLOWED_ERROR_FORMAT, $value));
+        UuidFilter::filter($value, false, false);
     }
 }