Add date rules (#678)

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>

CHANGELOG.md

@@ -5,6 +5,7 @@
 - New #665: Add methods `addErrorWithFormatOnly()` and `addErrorWithoutPostProcessing()` to `Result` object (@vjik)
 - Enh #668: Clarify psalm types in `Result` (@vjik)
 - New #670, #680: Add `Image` validation rule (@vjik, @arogachev)
+- New #678: Add `Date`, `DateTime` and `Time` validation rules (@vjik)
 
 ## 1.2.0 February 21, 2024
 

composer.json

@@ -52,7 +52,7 @@
         "yiisoft/yii-debug": "dev-master|dev-php80"
     },
     "suggest": {
-        "ext-intl": "Allows using IDN validation for emails",
+        "ext-intl": "Allows using date rules and IDN validation for emails",
         "ext-fileinfo": "To use image rule",
         "yiisoft/di": "To create rule handlers via Yii DI"
     },

docs/guide/en/built-in-rules.md

@@ -49,6 +49,12 @@ Here is a list of all available built-in rules, divided by category.
 
 - [Image](../../../src/Rule/Image/Image.php)
 
+### Date rules
+
+- [Date](../../../src/Rule/Date/Date.php)
+- [DateTime](../../../src/Rule/Date/DateTime.php)
+- [Time](../../../src/Rule/Date/Time.php)
+
 ### General purpose rules
 
 - [Callback](../../../src/Rule/Callback.php)

infection.json.dist

@@ -25,6 +25,17 @@
                 "Yiisoft\\Validator\\EmptyCondition\\NeverEmpty::__invoke",
                 "Yiisoft\\Validator\\EmptyCondition\\WhenNull::__invoke"
             ]
+        },
+        "IncrementInteger": {
+            "ignoreSourceCodeByRegex": [
+                ".*setDate\\(2024, 3, 29\\).*",
+                ".*setTime\\(0, 0\\).*"
+            ]
+        },
+        "DecrementInteger": {
+            "ignoreSourceCodeByRegex": [
+                ".*setDate\\(2024, 3, 29\\).*"
+            ]
         }
     }
 }

messages/ru/yii-validator.php

@@ -132,4 +132,23 @@
     'The allowed types are integer, float and string.' => 'Разрешённые типы: integer, float и string.',
     'Value must be no less than {min}.' => 'Значение должно быть не меньше {min}.',
     'Value must be no greater than {max}.' => 'Значение должно быть не больше {max}.',
+
+    /**
+     * @see \Yiisoft\Validator\Rule\Date\Date
+     * @see \Yiisoft\Validator\Rule\Date\DateTime
+     * @see \Yiisoft\Validator\Rule\Date\Time
+     */
+    'The value must be no early than {limit}.' => 'Значение должно быть не ранее {limit}.',
+    'The value must be no late than {limit}.' => 'Значение должно быть не позднее {limit}.',
+
+    /**
+     * @see \Yiisoft\Validator\Rule\Date\Date
+     * @see \Yiisoft\Validator\Rule\Date\DateTime
+     */
+    'Invalid date value.' => 'Некорректное значение даты.',
+
+    /**
+     * @see \Yiisoft\Validator\Rule\Date\Time
+     */
+    'Invalid time value.' => 'Некорректное значение времени.',
 ];

src/Exception/UnexpectedRuleException.php

@@ -36,28 +36,22 @@
  */
 final class UnexpectedRuleException extends InvalidArgumentException
 {
+    /**
+     * @param string|string[] $expectedClassName Expected class name(s) of a rule.
+     * @param object $actualObject An actual given object that's not an instance of `$expectedClassName`.
+     * @param int $code The Exception code.
+     * @param Throwable|null $previous The previous throwable used for the exception chaining.
+     */
     public function __construct(
-        /**
-         * @var string Expected class name of a rule.
-         */
-        string $expectedClassName,
-        /**
-         * @var object An actual given object that's not an instance of `$expectedClassName`.
-         */
+        string|array $expectedClassName,
         object $actualObject,
-        /**
-         * @var int The Exception code.
-         */
         int $code = 0,
-        /**
-         * @var Throwable|null The previous throwable used for the exception chaining.
-         */
         ?Throwable $previous = null,
     ) {
         parent::__construct(
             sprintf(
                 'Expected "%s", but "%s" given.',
-                $expectedClassName,
+                implode('", "', (array) $expectedClassName),
                 $actualObject::class
             ),
             $code,

src/Rule/Date/BaseDate.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Validator\Rule\Date;
+
+use Closure;
+use DateTimeInterface;
+use IntlDateFormatter;
+use Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait;
+use Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait;
+use Yiisoft\Validator\Rule\Trait\WhenTrait;
+use Yiisoft\Validator\RuleInterface;
+use Yiisoft\Validator\SkipOnEmptyInterface;
+use Yiisoft\Validator\SkipOnErrorInterface;
+use Yiisoft\Validator\WhenInterface;
+
+/**
+ * @see BaseDateHandler
+ *
+ * @psalm-type IntlDateFormatterFormat = IntlDateFormatter::FULL | IntlDateFormatter::LONG | IntlDateFormatter::MEDIUM | IntlDateFormatter::SHORT | IntlDateFormatter::NONE
+ * @psalm-import-type SkipOnEmptyValue from SkipOnEmptyInterface
+ * @psalm-import-type WhenType from WhenInterface
+ */
+abstract class BaseDate implements RuleInterface, SkipOnErrorInterface, WhenInterface, SkipOnEmptyInterface
+{
+    use SkipOnEmptyTrait;
+    use SkipOnErrorTrait;
+    use WhenTrait;
+
+    /**
+     * @psalm-param non-empty-string|null $timeZone
+     * @psalm-param SkipOnEmptyValue $skipOnEmpty
+     * @psalm-param WhenType $when
+     */
+    public function __construct(
+        private ?string $format,
+        private ?string $timeZone,
+        private ?string $locale,
+        private int|string|DateTimeInterface|null $min,
+        private int|string|DateTimeInterface|null $max,
+        private ?string $messageFormat,
+        private ?string $incorrectInputMessage,
+        private ?string $tooEarlyMessage,
+        private ?string $tooLateMessage,
+        private mixed $skipOnEmpty,
+        private bool $skipOnError,
+        private Closure|null $when,
+    ) {
+    }
+
+    public function getFormat(): ?string
+    {
+        return $this->format;
+    }
+
+    /**
+     * @return non-empty-string|null
+     */
+    public function getTimeZone(): ?string
+    {
+        return $this->timeZone;
+    }
+
+    public function getLocale(): ?string
+    {
+        return $this->locale;
+    }
+
+    public function getName(): string
+    {
+        return 'date';
+    }
+
+    public function getMin(): DateTimeInterface|int|string|null
+    {
+        return $this->min;
+    }
+
+    public function getMax(): DateTimeInterface|int|string|null
+    {
+        return $this->max;
+    }
+
+    public function getMessageFormat(): ?string
+    {
+        return $this->messageFormat;
+    }
+
+    public function getIncorrectInputMessage(): ?string
+    {
+        return $this->incorrectInputMessage;
+    }
+
+    public function getTooEarlyMessage(): ?string
+    {
+        return $this->tooEarlyMessage;
+    }
+
+    public function getTooLateMessage(): ?string
+    {
+        return $this->tooLateMessage;
+    }
+}