Add clock extension API for writing time-sensitive classes

Author: paulbalandan

infection.json5

@@ -30,7 +30,11 @@
         "ArrayItem": true,
         "ArrayItemRemoval": true,
         "ArrayOneItem": true,
-        "AssignCoalesce": true,
+        "AssignCoalesce": {
+            "ignore": [
+                "Nexus\\Clock\\InternalClock::getCurrent"
+            ]
+        },
         "Assignment": true,
         "AssignmentEqual": true,
         "BCMath": true,

src/Nexus/Clock/Extension/ClockAware.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Clock\Extension;
+
+use Nexus\Clock\Clock;
+use Nexus\Clock\FrozenClock;
+use Nexus\Clock\InternalClock;
+use Psr\Clock\ClockInterface;
+
+/**
+ * A trait to help write time-sensitive classes.
+ *
+ * @phpstan-require-implements ClockAwareInterface
+ */
+trait ClockAware
+{
+    private ?ClockInterface $clock = null;
+
+    public function setClock(?ClockInterface $clock): self
+    {
+        $this->clock = $clock;
+
+        return $this;
+    }
+
+    public function getClock(): Clock
+    {
+        if (null === $this->clock) {
+            return InternalClock::getCurrent();
+        }
+
+        if (! $this->clock instanceof Clock) {
+            return new FrozenClock($this->clock->now());
+        }
+
+        return $this->clock;
+    }
+
+    /**
+     * Gets the current timestamp.
+     */
+    private function now(): int
+    {
+        return $this->getClock()->now()->getTimestamp();
+    }
+}

src/Nexus/Clock/Extension/ClockAwareInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Clock\Extension;
+
+use Nexus\Clock\Clock;
+use Psr\Clock\ClockInterface;
+
+/**
+ * Interface for mutable classes that require access to a clock.
+ */
+interface ClockAwareInterface
+{
+    /**
+     * Sets the clock instance on the class.
+     */
+    public function setClock(?ClockInterface $clock): self;
+
+    /**
+     * Gets the clock instance.
+     */
+    public function getClock(): Clock;
+}

src/Nexus/Clock/Extension/ClockSensitive.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Clock\Extension;
+
+use Nexus\Clock\Clock;
+use Nexus\Clock\FrozenClock;
+use Nexus\Clock\InternalClock;
+use PHPUnit\Framework\Attributes\After;
+use PHPUnit\Framework\Attributes\Before;
+
+/**
+ * Trait to be used by test cases when mocking the clock.
+ */
+trait ClockSensitive
+{
+    private static ?Clock $originalClock = null;
+
+    #[Before]
+    protected static function saveClock(): void
+    {
+        self::$originalClock = InternalClock::getCurrent();
+    }
+
+    #[After]
+    protected static function restoreClock(): void
+    {
+        if (null !== self::$originalClock) {
+            InternalClock::set(self::$originalClock);
+            self::$originalClock = null;
+        }
+    }
+
+    /**
+     * Mocks the current time to a fixed non-moving clock.
+     */
+    private static function mockTime(\DateTimeImmutable|string $mock = 'now', bool $saveClock = true): Clock
+    {
+        if ($saveClock) {
+            self::saveClock();
+        }
+
+        InternalClock::set(match (true) {
+            $mock instanceof \DateTimeImmutable => new FrozenClock($mock),
+            default => new FrozenClock(new \DateTimeImmutable($mock)),
+        });
+
+        return InternalClock::getCurrent();
+    }
+}

src/Nexus/Clock/Extension/ImmutableClockAware.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Clock\Extension;
+
+use Nexus\Clock\InternalClock;
+use Psr\Clock\ClockInterface;
+
+/**
+ * A trait to help write time-sensitive immutable classes.
+ *
+ * @property null|ClockInterface $clock
+ */
+trait ImmutableClockAware
+{
+    /**
+     * Gets the current timestamp.
+     */
+    private function now(): int
+    {
+        $clock = $this->clock ?? InternalClock::getCurrent();
+
+        return $clock->now()->getTimestamp();
+    }
+}

src/Nexus/Clock/InternalClock.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Clock;
+
+/**
+ * A reference to the internal clock.
+ *
+ * This is primarily useful for mocking the clock in tests.
+ * Classes should not use this class directly, but instead
+ * use the `Clock` interface or the two traits `ClockAware`
+ * and `ImmutableClockAware`.
+ *
+ * @internal
+ */
+final class InternalClock implements Clock
+{
+    private static ?Clock $internalClock;
+
+    public function __construct(
+        private readonly ?Clock $innerClock = null,
+        private ?\DateTimeZone $timezone = null,
+    ) {}
+
+    /**
+     * Returns the current internal clock.
+     *
+     * If no internal clock has been set, a new instance of SystemClock
+     * will be created with the UTC timezone.
+     */
+    public static function getCurrent(): Clock
+    {
+        self::$internalClock ??= new SystemClock('UTC');
+
+        return self::$internalClock;
+    }
+
+    /**
+     * Sets the internal clock.
+     */
+    public static function set(?Clock $clock): void
+    {
+        self::$internalClock = $clock;
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        $now = ($this->innerClock ?? self::getCurrent())->now();
+
+        if (null !== $this->timezone) {
+            $now = $now->setTimezone($this->timezone);
+        }
+
+        return $now;
+    }
+
+    public function sleep(float|int $seconds): void
+    {
+        ($this->innerClock ?? self::getCurrent())->sleep($seconds);
+    }
+}

tests/AutoReview/SourceCodeTest.php

@@ -179,7 +179,7 @@ public function testSourceClassDoesNotHaveUnnecessaryProtectedMethods(string $cl
     {
         $rc = new \ReflectionClass($class);
 
-        if ($rc->isAbstract() || $rc->isInterface()) {
+        if ($rc->isAbstract() || $rc->isInterface() || $rc->isTrait()) {
             $this->expectNotToPerformAssertions();
 
             return;

tests/AutoReview/TestCodeTest.php

@@ -13,6 +13,7 @@
 
 namespace Nexus\Tests\AutoReview;
 
+use Nexus\Clock\Extension\ClockSensitive;
 use Nexus\Collection\Collection;
 use Nexus\Option\None;
 use Nexus\Option\Some;
@@ -40,6 +41,7 @@ final class TestCodeTest extends TestCase
 
     private const RECOGNISED_GROUP_NAMES = [
         'auto-review',
+        'clock-sensitive',
         'package-test',
         'static-analysis',
         'unit-test',
@@ -357,6 +359,33 @@ public function testEachTestClassIsFinalOrAbstractAndIsInternal(string $class):
         self::assertStringContainsString('@internal', $docComment, \sprintf('Test class "%s" should be marked as @internal.', $class));
     }
 
+    /**
+     * @param class-string<TestCase> $class
+     */
+    #[DataProvider('provideTestClassCases')]
+    public function testClockSensitiveTestUsesClockSensitiveTraitAndGroup(string $class): void
+    {
+        $rc = new \ReflectionClass($class);
+
+        if (\in_array(ClockSensitive::class, $rc->getTraitNames(), true)) {
+            $attributes = array_map(static function (\ReflectionAttribute $attribute): string {
+                $groupAttribute = $attribute->newInstance();
+                \assert($groupAttribute instanceof Group);
+
+                return $groupAttribute->name();
+            }, $rc->getAttributes(Group::class));
+
+            self::assertContains('clock-sensitive', $attributes, \sprintf(
+                'Time-sensitive test class "%s" should have the #[Group(\'clock-sensitive\')] attribute.',
+                $class,
+            ));
+
+            return;
+        }
+
+        $this->expectNotToPerformAssertions();
+    }
+
     /**
      * @return iterable<class-string<TestCase>, array{class-string<TestCase>}>
      */