Add ClockAware and ImmutableClockAware for writing time-sensitive classes

Author: paulbalandan

src/Nexus/Clock/Extension/ClockAware.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * 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\SystemClock;
+use Psr\Clock\ClockInterface;
+
+/**
+ * A trait to help write time-sensitive classes.
+ *
+ * @phpstan-require-implements ClockAwareInterface
+ */
+trait ClockAware
+{
+    private ?Clock $clock = null;
+
+    public function setClock(?ClockInterface $clock): self
+    {
+        if (null !== $clock && ! $clock instanceof Clock) {
+            $clock = new FrozenClock($clock->now());
+        }
+
+        $this->clock = $clock;
+
+        return $this;
+    }
+
+    public function getClock(): Clock
+    {
+        return $this->clock ?? new SystemClock('UTC');
+    }
+
+    /**
+     * Gets the current timestamp.
+     */
+    private function now(): int
+    {
+        return $this->getClock()->now()->getTimestamp();
+    }
+}

src/Nexus/Clock/Extension/ClockAwareInterface.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * 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. If the clock is not an instance of
+     * `Nexus\Clock\Clock`, it will be wrapped in a `Nexus\Clock\FrozenClock`.
+     * If `null` is passed, the class will use a `Nexus\Clock\SystemClock`.
+     */
+    public function setClock(?ClockInterface $clock): self;
+
+    /**
+     * Gets the clock instance.
+     */
+    public function getClock(): Clock;
+}

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 <[email protected]>
+ *
+ * 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;
+
+/**
+ * A trait to help write time-sensitive immutable classes.
+ *
+ * Using classes must ensure that a readonly `Clock` instance is already
+ * injected into the class, preferably in the constructor.
+ *
+ * @property Clock $clock
+ */
+trait ImmutableClockAware
+{
+    /**
+     * Gets the current timestamp.
+     */
+    private function now(): int
+    {
+        return $this->clock->now()->getTimestamp();
+    }
+}

tests/Clock/Extension/ClockAwareTest.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Tests\Clock\Extension;
+
+use Nexus\Clock\Extension\ClockAware;
+use Nexus\Clock\Extension\ClockAwareInterface;
+use Nexus\Clock\FrozenClock;
+use Nexus\Clock\SystemClock;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+use Psr\Clock\ClockInterface;
+
+/**
+ * @internal
+ */
+#[CoversTrait(ClockAware::class)]
+#[Group('unit-test')]
+final class ClockAwareTest extends TestCase
+{
+    /**
+     * @param class-string $expected
+     */
+    #[DataProvider('provideSetClockCases')]
+    public function testSetClock(?ClockInterface $clock, int $time, string $expected): void
+    {
+        $instance = new MutableClass();
+        $instance->setClock($clock);
+
+        self::assertGreaterThanOrEqual($time, $instance->getNow());
+        self::assertInstanceOf($expected, $instance->getClock());
+    }
+
+    /**
+     * @return iterable<string, array{null|ClockInterface, int, class-string}>
+     */
+    public static function provideSetClockCases(): iterable
+    {
+        $dateTime = new \DateTimeImmutable('2025-05-19 12:00:00', new \DateTimeZone('UTC'));
+
+        yield 'null' => [null, time(), SystemClock::class];
+
+        yield 'system clock' => [new SystemClock('UTC'), time(), SystemClock::class];
+
+        yield 'frozen clock' => [new FrozenClock($dateTime), $dateTime->getTimestamp(), FrozenClock::class];
+
+        yield 'psr clock' => [new class implements ClockInterface {
+            public function now(): \DateTimeImmutable
+            {
+                return new \DateTimeImmutable('2025-05-19 12:00:00', new \DateTimeZone('UTC'));
+            }
+        }, $dateTime->getTimestamp(), FrozenClock::class];
+    }
+}
+
+/**
+ * @internal
+ */
+final class MutableClass implements ClockAwareInterface
+{
+    use ClockAware;
+
+    public function getNow(): int
+    {
+        return $this->now();
+    }
+}

tests/Clock/Extension/ImmutableClockAwareTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Tests\Clock\Extension;
+
+use Nexus\Clock\Clock;
+use Nexus\Clock\Extension\ImmutableClockAware;
+use Nexus\Clock\FrozenClock;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[CoversTrait(ImmutableClockAware::class)]
+#[Group('unit-test')]
+final class ImmutableClockAwareTest extends TestCase
+{
+    public function testNowUsingTrait(): void
+    {
+        $clock = new FrozenClock(new \DateTimeImmutable('2025-05-19 12:00:00', new \DateTimeZone('UTC')));
+        $object = new ImmutableClass($clock);
+
+        self::assertSame($clock->now()->getTimestamp(), $object->getNow());
+    }
+}
+
+/**
+ * @internal
+ */
+final readonly class ImmutableClass
+{
+    use ImmutableClockAware;
+
+    public function __construct(
+        private Clock $clock,
+    ) {}
+
+    public function getNow(): int
+    {
+        return $this->now();
+    }
+}