add regex argument to string() & nullOrString()

phpstan-baseline.neon

@@ -192,6 +192,18 @@ parameters:
 			count: 1
 			path: tests/Unit/Util/ValueObjectTraitTest.php
 
+		-
+			message: '#^Parameter \$regex of static method class@anonymous/tests/Unit/Util/ValueObjectTraitTest\.php\:1133\:\:nullOrString\(\) expects non\-empty\-string\|null, '''' given\.$#'
+			identifier: argument.type
+			count: 1
+			path: tests/Unit/Util/ValueObjectTraitTest.php
+
+		-
+			message: '#^Parameter \$regex of static method class@anonymous/tests/Unit/Util/ValueObjectTraitTest\.php\:1243\:\:string\(\) expects non\-empty\-string\|null, '''' given\.$#'
+			identifier: argument.type
+			count: 1
+			path: tests/Unit/Util/ValueObjectTraitTest.php
+
 		-
 			message: '#^Unable to resolve the template type T in call to method static method class@anonymous/tests/Unit/Util/ValueObjectTraitTest\.php\:332\:\:enum\(\)$#'
 			identifier: argument.templateType

src/Util/ValueObjectTrait.php

@@ -362,10 +362,11 @@ final protected static function nullOrMultiLink(array $values, string $key): ?Mu
     /**
      * Returns null if the value is not set or a trimmed non-empty string.
      *
-     * @param array<mixed>     $values
-     * @param non-empty-string $key
+     * @param array<mixed>          $values
+     * @param non-empty-string      $key
+     * @param null|non-empty-string $regex
      */
-    final protected static function nullOrString(array $values, string $key, ?int $maxLength = null): ?string
+    final protected static function nullOrString(array $values, string $key, ?int $maxLength = null, ?string $regex = null): ?string
     {
         if (!\array_key_exists($key, $values)) {
             return null;
@@ -376,6 +377,11 @@ final protected static function nullOrString(array $values, string $key, ?int $m
             Assert::maxLength($values[$key], $maxLength);
         }
 
+        if (null !== $regex) {
+            Assert::stringNotEmpty($regex);
+            Assert::regex($values[$key], $regex);
+        }
+
         try {
             return TrimmedNonEmptyString::from($values[$key])->toString();
         } catch (\InvalidArgumentException) {
@@ -386,17 +392,23 @@ final protected static function nullOrString(array $values, string $key, ?int $m
     /**
      * Returns a trimmed non-empty string.
      *
-     * @param array<mixed>     $values
-     * @param non-empty-string $key
+     * @param array<mixed>          $values
+     * @param non-empty-string      $key
+     * @param null|non-empty-string $regex
      */
-    final protected static function string(array $values, string $key, ?int $maxLength = null): string
+    final protected static function string(array $values, string $key, ?int $maxLength = null, ?string $regex = null): string
     {
         Assert::keyExists($values, $key);
 
         if (null !== $maxLength) {
             Assert::maxLength($values[$key], $maxLength);
         }
 
+        if (null !== $regex) {
+            Assert::stringNotEmpty($regex);
+            Assert::regex($values[$key], $regex);
+        }
+
         return TrimmedNonEmptyString::fromString($values[$key])->toString();
     }
 

tests/Unit/Util/ValueObjectTraitTest.php

@@ -1113,6 +1113,52 @@ public function nullOrStringThrowsExceptionWhenMaxLengthIsLessThenOne(): void
         $class::nullOrString($values, 'key', 0);
     }
 
+    #[Test]
+    public function nullOrStringWithRegex(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::nullOrString as public;
+            }
+        };
+
+        $values = ['key' => 'hello-world'];
+
+        self::assertSame('hello-world', $class::nullOrString($values, 'key', regex: '/^hello-world$/'));
+    }
+
+    #[Test]
+    public function nullOrStringThrowsExceptionWhenRegexEmpty(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::nullOrString as public;
+            }
+        };
+
+        $values = ['key' => 'hello-world'];
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $class::nullOrString($values, 'key', regex: '');
+    }
+
+    #[Test]
+    public function nullOrStringThrowsExceptionWhenRegexNotMatch(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::nullOrString as public;
+            }
+        };
+
+        $values = ['key' => 'not-matching'];
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $class::nullOrString($values, 'key', regex: '/^hello-world$/');
+    }
+
     #[Test]
     public function string(): void
     {
@@ -1177,6 +1223,52 @@ public function stringThrowsExceptionWhenMaxLengthExceeded(): void
         $class::string($values, 'key', 5);
     }
 
+    #[Test]
+    public function stringWithRegex(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::string as public;
+            }
+        };
+
+        $values = ['key' => 'hello-world'];
+
+        self::assertSame('hello-world', $class::string($values, 'key', regex: '/^hello-world$/'));
+    }
+
+    #[Test]
+    public function stringThrowsExceptionWhenRegexEmpty(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::string as public;
+            }
+        };
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $values = ['key' => 'hello-world'];
+
+        $class::string($values, 'key', regex: '');
+    }
+
+    #[Test]
+    public function stringThrowsExceptionWhenRegexNotMatch(): void
+    {
+        $class = new class() {
+            use ValueObjectTrait {
+                ValueObjectTrait::string as public;
+            }
+        };
+
+        $values = ['key' => 'not-matching'];
+
+        $this->expectException(\InvalidArgumentException::class);
+
+        $class::string($values, 'key', regex: '/^hello-world$/');
+    }
+
     #[Test]
     public function nullOrEditable(): void
     {