feat: added Regex rule

Author: andrepimpao

src/ChainedValidatorInterface.php

@@ -95,6 +95,13 @@ public function range(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public function regex(
+        string $pattern,
+        bool $match = true,
+        ?callable $normalizer = null,
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public function rule(
         RuleInterface $constraint
     ): ChainedValidatorInterface&Validator;

src/Exception/RegexException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Exception;
+
+class RegexException extends ValidationException {}

src/Rule/Regex.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Rule;
+
+use ProgrammatorDev\Validator\Exception\RegexException;
+use ProgrammatorDev\Validator\Exception\UnexpectedTypeException;
+use ProgrammatorDev\Validator\Exception\UnexpectedValueException;
+
+class Regex extends AbstractRule implements RuleInterface
+{
+    /** @var ?callable */
+    private $normalizer;
+    private string $message = 'The {{ name }} value is not valid.';
+
+    public function __construct(
+        private readonly string $pattern,
+        private readonly bool $match = true,
+        ?callable $normalizer = null,
+        ?string $message = null
+    )
+    {
+        $this->normalizer = $normalizer;
+        $this->message = $message ?? $this->message;
+    }
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        if (!\is_scalar($value) && !$value instanceof \Stringable) {
+            throw new UnexpectedTypeException('string|\Stringable', get_debug_type($value));
+        }
+
+        $value = (string) $value;
+
+        if ($this->normalizer !== null) {
+            $value = ($this->normalizer)($value);
+        }
+
+        if (($regex = @\preg_match($this->pattern, $value)) === false) {
+            throw new UnexpectedValueException('Invalid regular expression pattern.');
+        }
+
+        if ($this->match xor $regex) {
+            throw new RegexException(
+                message: $this->message,
+                parameters: [
+                    'name' => $name,
+                    'value' => $value,
+                    'pattern' => $this->pattern
+                ]
+            );
+        }
+    }
+}

src/StaticValidatorInterface.php

@@ -94,6 +94,13 @@ public static function range(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public static function regex(
+        string $pattern,
+        bool $match = true,
+        ?callable $normalizer = null,
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public static function rule(
         RuleInterface $constraint
     ): ChainedValidatorInterface&Validator;

tests/RegexTest.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Test;
+
+use ProgrammatorDev\Validator\Exception\RegexException;
+use ProgrammatorDev\Validator\Rule\Regex;
+use ProgrammatorDev\Validator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleUnexpectedValueTrait;
+
+class RegexTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        $unexpectedPatternMessage = '/Invalid regular expression pattern./';
+        $unexpectedTypeMessage = '/Expected value of type "array|\Stringable", "(.*)" given./';
+
+        yield 'invalid pattern' => [new Regex('invalid'), 'abc', $unexpectedPatternMessage];
+        yield 'invalid value type' => [new Regex('/[a-z]/'), ['abc'], $unexpectedTypeMessage];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $value = 'abc';
+        $exception = RegexException::class;
+        $message = '/The (.*) value is not valid./';
+
+        yield 'match true' => [new Regex('/[0-9]/'), $value, $exception, $message];
+        yield 'match false' => [new Regex('/[a-z]/', match: false), $value, $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        $value = 'abc';
+
+        yield 'match true' => [new Regex('/[a-z]/'), $value];
+        yield 'match false' => [new Regex('/[0-9]/', match: false), $value];
+        yield 'normalizer' => [new Regex('/^\S*$/', normalizer: 'trim'), 'abc '];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new Regex(
+                pattern: '/[a-z]/',
+                message: 'The {{ name }} value does not match the pattern {{ pattern }}.'
+            ),
+            '123',
+            'The test value does not match the pattern "/[a-z]/".'
+        ];
+    }
+}