feat: added DateTime rule

Author: andrepimpao

src/ChainedValidatorInterface.php

@@ -31,6 +31,11 @@ public function country(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public function dateTime(
+        string $format = 'Y-m-d H:i:s',
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public function eachKey(
         Validator $validator,
         ?string $message = null

src/Exception/DateTimeException.php

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

src/Rule/DateTime.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Rule;
+
+use ProgrammatorDev\Validator\Exception\DateTimeException;
+use ProgrammatorDev\Validator\Exception\UnexpectedTypeException;
+
+class DateTime extends AbstractRule implements RuleInterface
+{
+    private string $message = 'The {{ name }} value is not a valid datetime.';
+
+    public function __construct(
+        private readonly string $format = 'Y-m-d H:i:s',
+        ?string $message = null
+    )
+    {
+        $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;
+
+        \DateTimeImmutable::createFromFormat($this->format, $value);
+
+        $errors = \DateTimeImmutable::getLastErrors();
+
+        if ($errors !== false && ($errors['error_count'] > 0 || $errors['warning_count'] > 0)) {
+            throw new DateTimeException(
+                message: $this->message,
+                parameters: [
+                    'name' => $name,
+                    'value' => $value,
+                    'format' => $this->format
+                ]
+            );
+        }
+    }
+}

src/StaticValidatorInterface.php

@@ -30,6 +30,11 @@ public static function country(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public static function dateTime(
+        string $format = 'Y-m-d H:i:s',
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public static function eachKey(
         Validator $validator,
         ?string $message = null

tests/DateTimeTest.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Test;
+
+use ProgrammatorDev\Validator\Exception\DateTimeException;
+use ProgrammatorDev\Validator\Rule\DateTime;
+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 DateTimeTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        $unexpectedTypeMessage = '/Expected value of type "string|\Stringable", "(.*)" given./';
+
+        yield 'invalid value type' => [new DateTime(), ['2024-01-01 00:00:00'], $unexpectedTypeMessage];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $value = 'invalid';
+        $exception = DateTimeException::class;
+        $message = '/The (.*) value is not a valid datetime./';
+
+        yield 'invalid datetime' => [new DateTime(), $value, $exception, $message];
+        yield 'invalid format' => [new DateTime(format: 'invalid'), '2024-01-01 00:00:00', $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'datetime' => [new DateTime(), '2024-01-01 00:00:00'];
+        yield 'format' => [new DateTime(format: 'Y-m-d'), '2024-01-01'];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new DateTime(
+                message: 'The {{ name }} datetime does not match the format {{ format }}.'
+            ),
+            '2024-01-01',
+            'The test datetime does not match the format "Y-m-d H:i:s".'
+        ];
+    }
+}