Added mustBeBeforeOrEqualTo and mustBeBeforeOrEqualToInTimeZone

src/Exception/MomentIsNotBeforeOrEqualTo.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DigitalCraftsman\DateTimePrecision\Exception;
+
+/**
+ * @psalm-immutable
+ *
+ * @codeCoverageIgnore
+ */
+final class MomentIsNotBeforeOrEqualTo extends \InvalidArgumentException
+{
+    public function __construct()
+    {
+        parent::__construct('The moment is not before or equal to but must be.');
+    }
+}

src/Moment.php

@@ -783,4 +783,39 @@ public function mustNotBeBeforeInTimeZone(
                 : new Exception\MomentIsBefore();
         }
     }
+
+    /**
+     * @param ?callable(): \Throwable $otherwiseThrow
+     *
+     * @throws \Throwable
+     * @throws Exception\MomentIsNotBeforeOrEqualTo
+     */
+    public function mustBeBeforeOrEqualTo(
+        self $moment,
+        ?callable $otherwiseThrow = null,
+    ): void {
+        if ($this->isNotBeforeOrEqualTo($moment)) {
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
+                : new Exception\MomentIsNotBeforeOrEqualTo();
+        }
+    }
+
+    /**
+     * @param ?callable(): \Throwable $otherwiseThrow
+     *
+     * @throws \Throwable
+     * @throws Exception\MomentIsNotBeforeOrEqualTo
+     */
+    public function mustBeBeforeOrEqualToInTimeZone(
+        Time | Weekday | Date | Month | Year $moment,
+        \DateTimeZone $timeZone,
+        ?callable $otherwiseThrow = null,
+    ): void {
+        if ($this->isNotBeforeOrEqualToInTimeZone($moment, $timeZone)) {
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
+                : new Exception\MomentIsNotBeforeOrEqualTo();
+        }
+    }
 }

tests/Moment/MustBeBeforeOrEqualToInTimeZoneTest.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DigitalCraftsman\DateTimePrecision\Moment;
+
+use DigitalCraftsman\DateTimePrecision\Date;
+use DigitalCraftsman\DateTimePrecision\Exception\MomentIsNotBeforeOrEqualTo;
+use DigitalCraftsman\DateTimePrecision\Moment;
+use DigitalCraftsman\DateTimePrecision\Month;
+use DigitalCraftsman\DateTimePrecision\Test\Exception\CustomMomentIsNotBeforeOrEqualToInTimeZone;
+use DigitalCraftsman\DateTimePrecision\Time;
+use DigitalCraftsman\DateTimePrecision\Weekday;
+use DigitalCraftsman\DateTimePrecision\Year;
+use PHPUnit\Framework\TestCase;
+
+/** @coversDefaultClass \DigitalCraftsman\DateTimePrecision\Moment */
+final class MustBeBeforeOrEqualToInTimeZoneTest extends TestCase
+{
+    /**
+     * @test
+     *
+     * @param ?class-string<\Throwable> $expectedResult
+     *
+     * @dataProvider dataProvider
+     *
+     * @covers ::mustBeBeforeOrEqualToInTimeZone
+     */
+    public function must_be_before_or_equal_to_in_time_zone_works(
+        ?string $expectedResult,
+        Moment $moment,
+        Time | Weekday | Date | Month | Year $comparator,
+        \DateTimeZone $timeZone,
+        ?callable $otherwiseThrow,
+    ): void {
+        // -- Act & Assert
+        if ($expectedResult !== null) {
+            $this->expectException($expectedResult);
+        } else {
+            $this->expectNotToPerformAssertions();
+        }
+
+        $moment->mustBeBeforeOrEqualToInTimeZone(
+            $comparator,
+            $timeZone,
+            $otherwiseThrow,
+        );
+    }
+
+    /**
+     * @return array<string, array{
+     *   0: ?string,
+     *   1: Moment,
+     *   2: Time | Weekday | Date | Month | Year,
+     *   3: \DateTimeZone,
+     *   4: ?callable(): \Throwable
+     * }>
+     */
+    public static function dataProvider(): array
+    {
+        return [
+            'without exception' => [
+                null,
+                Moment::fromStringInTimeZone('2022-10-08 15:00:00', new \DateTimeZone('Europe/Berlin')),
+                Time::fromString('16:00:00'),
+                new \DateTimeZone('Europe/Berlin'),
+                null,
+            ],
+            'default exception' => [
+                MomentIsNotBeforeOrEqualTo::class,
+                Moment::fromStringInTimeZone('2022-10-08 16:00:00', new \DateTimeZone('Europe/Berlin')),
+                Time::fromString('15:00:00'),
+                new \DateTimeZone('Europe/Berlin'),
+                null,
+            ],
+            'custom exception' => [
+                CustomMomentIsNotBeforeOrEqualToInTimeZone::class,
+                Moment::fromStringInTimeZone('2022-10-08 16:00:00', new \DateTimeZone('Europe/Berlin')),
+                Time::fromString('15:00:00'),
+                new \DateTimeZone('Europe/Berlin'),
+                static fn () => new CustomMomentIsNotBeforeOrEqualToInTimeZone(),
+            ],
+        ];
+    }
+}

tests/Moment/MustBeBeforeOrEqualToTest.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DigitalCraftsman\DateTimePrecision\Moment;
+
+use DigitalCraftsman\DateTimePrecision\Exception\MomentIsNotBeforeOrEqualTo;
+use DigitalCraftsman\DateTimePrecision\Moment;
+use DigitalCraftsman\DateTimePrecision\Test\Exception\CustomMomentIsNotBeforeOrEqualTo;
+use PHPUnit\Framework\TestCase;
+
+/** @coversDefaultClass \DigitalCraftsman\DateTimePrecision\Moment */
+final class MustBeBeforeOrEqualToTest extends TestCase
+{
+    /**
+     * @test
+     *
+     * @param ?class-string<\Throwable> $expectedResult
+     *
+     * @dataProvider dataProvider
+     *
+     * @covers ::mustBeBeforeOrEqualTo
+     */
+    public function must_be_before_or_equal_to_works(
+        ?string $expectedResult,
+        Moment $moment,
+        Moment $comparator,
+        ?callable $otherwiseThrow,
+    ): void {
+        // -- Act & Assert
+        if ($expectedResult !== null) {
+            $this->expectException($expectedResult);
+        } else {
+            $this->expectNotToPerformAssertions();
+        }
+
+        $moment->mustBeBeforeOrEqualTo(
+            $comparator,
+            $otherwiseThrow,
+        );
+    }
+
+    /**
+     * @return array<string, array{
+     *   0: ?string,
+     *   1: Moment,
+     *   2: Moment,
+     *   3: ?callable(): \Throwable
+     * }>
+     */
+    public static function dataProvider(): array
+    {
+        return [
+            'without exception' => [
+                null,
+                Moment::fromString('2022-10-08 15:00:00'),
+                Moment::fromString('2022-10-08 16:00:00'),
+                null,
+            ],
+            'default exception' => [
+                MomentIsNotBeforeOrEqualTo::class,
+                Moment::fromString('2022-10-08 16:00:00'),
+                Moment::fromString('2022-10-08 15:00:00'),
+                null,
+            ],
+            'custom exception' => [
+                CustomMomentIsNotBeforeOrEqualTo::class,
+                Moment::fromString('2022-10-08 16:00:00'),
+                Moment::fromString('2022-10-08 15:00:00'),
+                static fn () => new CustomMomentIsNotBeforeOrEqualTo(),
+            ],
+        ];
+    }
+}

tests/Test/Exception/CustomMomentIsNotBeforeOrEqualTo.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DigitalCraftsman\DateTimePrecision\Test\Exception;
+
+final class CustomMomentIsNotBeforeOrEqualTo extends \InvalidArgumentException
+{
+}

tests/Test/Exception/CustomMomentIsNotBeforeOrEqualToInTimeZone.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DigitalCraftsman\DateTimePrecision\Test\Exception;
+
+final class CustomMomentIsNotBeforeOrEqualToInTimeZone extends \InvalidArgumentException
+{
+}