Release 4.0.0

Wrapping an object should not call it just to validate the return value.
Instead, we check the method signature when the object is wrapped, and
the return value at runtime. We were implicitly checking it already
with the `assert()` calls.

.gitattributes

@@ -6,4 +6,3 @@
 /.gitignore                     export-ignore
 /phpstan.neon.dist              export-ignore
 /phpunit.xml.dist               export-ignore
-/psalm.xml.dist                 export-ignore

.github/dependabot.yml

@@ -0,0 +1,15 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    commit-message:
+      include: "scope"
+      prefix: "github-actions"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"

.github/settings.yml

@@ -0,0 +1,2 @@
+# https://probot.github.io/apps/settings/
+_extends: beste/.github

.github/workflows/tests.yml

@@ -4,26 +4,26 @@ on:
   pull_request:
   push:
     branches:
-      - 'main'
+      - '4.x'
 
 jobs:
   tests:
     name: PHP ${{ matrix.php }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
 
     strategy:
       matrix:
         php:
-          - "7.4"
+          - "8.3"
-          - "8.0"
+          - "8.4"
-          - "8.1"
+          - "8.5"
-        dependencies:
+        include:
-          - "lowest"
+          - php: "8.6"
-          - "highest"
+            composer-options: "--ignore-platform-req=php+"
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
@@ -33,9 +33,8 @@ jobs:
         env:
           COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: "ramsey/composer-install@v1"
+      - uses: "ramsey/composer-install@v4"
         with:
-          dependency-versions: "${{ matrix.dependencies }}"
           composer-options: "${{ matrix.composer-options }}"
 
       - name: Setup problem matchers for PHP
@@ -44,9 +43,6 @@ jobs:
       - name: Run PHPStan
         run: vendor/bin/phpstan analyse --error-format=github
 
-      - name: Run Psalm
-        run: vendor/bin/psalm --output-format=github
-
       - name: Setup Problem Matchers for PHPUnit
         run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
 

.gitignore

@@ -4,4 +4,3 @@
 /composer.lock
 /phpstan.neon
 /phpunit.xml
-/psalm.xml

CHANGELOG.md

@@ -1,8 +1,41 @@
 # CHANGELOG
 
-## [Unreleased]
+## Unreleased
+
+## 4.0.0 - 2026-08-23
+
+* Dropped support for PHP <8.3.
+* Removed the deprecated `Beste\Clock` interface. Clock implementations now implement 
+  `Psr\Clock\ClockInterface` directly.
+* `WrappingClock` will throw an `InvalidArgumentException` if the given object doesn't behave like
+  a PSR-20 clock and will throw an `UnexpectedValueException` if a later call does not return
+  `DateTimeImmutable`.
+
+## 3.1.0 - 2026-08-22
+
+Deprecated `Beste\Clock` in favor of `Psr\Clock\ClockInterface`. The implementations continue to implement
+the deprecated interface for backwards compatibility. Please type against `Psr\Clock\ClockInterface`.
+`Beste\Clock` will be removed in 4.0.
+
+## 3.0.0 - 2022-11-26
+This release replaces `stella-maris/clock` with `psr/clock`.
+
+## 2.3.1 - 2022-11-25
+This release reverts the change to implement `psr/clock` directly, to not break dependents who rely on `stella-maris/clock`
+
+## 2.3.0 - 2022-11-25
+This release re-introduces support for PHP ^8.0 and implements the freshly released `psr/clock` (PSR-20) directly.
+
+## 2.2.0 - 2022-11-04
+This release drops support for PHP <8.1.
+
+## 2.1.0 - 2022-04-22
+Adds the `WrappingClock` which allows using an object with a `now()` method returning a `DateTimeImmutable` object
+as a "real" clock.
+
+## 2.0.0 - 2022-04-20
+This release introduces a compatibility layer with the PSR-20 draft, allowing us to already
+get some interoperability by depending on a shared interface.
 
 ## 1.0.0 - 2021-12-10
 Initial Release
-
-[Unreleased]: https://github.com/beste/clock/compare/1.0.0...main

README.md

@@ -4,7 +4,7 @@
 [![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/beste/clock)](https://packagist.org/packages/beste/clock)
 [![Tests](https://github.com/beste/clock/actions/workflows/tests.yml/badge.svg)](https://github.com/beste/clock/actions/workflows/tests.yml)
 
-A collection of Clock implementations.
+A collection of [PSR-20](https://www.php-fig.org/psr/psr-20/) Clock implementations.
 
 ## Table of Contents
 
@@ -15,6 +15,7 @@ A collection of Clock implementations.
     - [`UTCClock`](#utcclock) - The clock that you should™ use
     - [`FrozenClock`](#frozenclock) - A clock that stopped moving (perfect for tests)
     - [`MinuteClock`](#minuteclock) - Who cares about seconds or even less?
+    - [`WrappingClock`](#wrappingclock) - Allows wrapping a non-clock with a `now()` method in a clock
 - [Running Tests](#running-tests)
     
 ## Installation
@@ -113,8 +114,8 @@ printf("\nAfter turning back the clock 5 minutes, it's %s", $frozenClock->now()-
 
 ### `MinuteClock`
 
-In some cases, microseconds, milliseconds, or even seconds are too precise for some use cases - sometimes it's just
+In some cases, microseconds, milliseconds, or even seconds are too precise. Sometimes it is enough to know that
-enough if something happened in the same minute. Using the minute
+something happened within the same minute. `MinuteClock` removes seconds and fractions of a second from another clock.
 
 ```php
 # examples/minute_clock.php
@@ -136,7 +137,40 @@ printf("For %s, the minute clock still returns %s\n",
     $frozenClock->now()->format('H:i:s'),
     $clock->now()->format('H:i:s')
 );
+```
 
+### `WrappingClock`
+
+If you already have an object with a `now()` method returning a `DateTimeImmutable`, you can wrap it in a
+`WrappingClock` to make it a PSR-20 clock.
+
+```php
+# examples/wrapping_clock.php
+
+use Beste\Clock\WrappingClock;
+
+// Create a frozen $now so that we can test the wrapping clock.
+$now = new DateTimeImmutable('2012-04-24 12:00:00');
+
+// Create an object that is NOT a clock, but has a now() method returning the frozen $now.
+$clock = new class($now) {
+    private \DateTimeImmutable $now;
+
+    public function __construct(\DateTimeImmutable $now)
+    {
+        $this->now = $now;
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        return $this->now;
+    }
+};
+
+// We can now wrap the object in a clock.
+$wrappedClock = WrappingClock::wrapping($clock);
+
+assert($now->format(DATE_ATOM) === $wrappedClock->now()->format(DATE_ATOM));
 ```
 
 ## Running tests

SECURITY.md

@@ -0,0 +1,5 @@
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.

composer.json

@@ -11,45 +11,41 @@
         }
     ],
     "require": {
-        "php": "~7.4.0 || ~8.0.0 || ~8.1.0"
+        "php": "^8.3",
+        "psr/clock": "^1.0"
     },
     "require-dev": {
-        "phpstan/extension-installer": "^1.1",
+        "phpstan/extension-installer": "^1.4.1",
-        "phpstan/phpstan": "^1.0",
+        "phpstan/phpstan": "^2.1",
-        "phpstan/phpstan-phpunit": "^1.0",
+        "phpstan/phpstan-phpunit": "^2.0",
-        "phpstan/phpstan-strict-rules": "^1.0",
+        "phpstan/phpstan-strict-rules": "^2.0",
-        "phpunit/phpunit": "^9.5.10",
+        "phpunit/phpunit": "^12.5"
-        "psalm/plugin-phpunit": "^0.16.0",
-        "vimeo/psalm": "^4.15"
     },
     "autoload": {
         "psr-4": {
-            "Beste\\Clock\\": "src/Clock"
+            "Beste\\Clock\\": "src"
-        },
+        }
-        "files": [
-            "src/psr-polyfill.php",
-            "src/Clock.php"
-        ]
     },
     "autoload-dev": {
         "psr-4": {
-            "Beste\\Clock\\Tests\\": "tests/Clock"
+            "Beste\\Clock\\Tests\\": "tests"
         }
     },
     "provide": {
         "psr/clock-implementation": "1.0"
     },
     "config": {
-        "sort-packages": true
+        "sort-packages": true,
+        "allow-plugins": {
+            "phpstan/extension-installer": true
+        }
     },
     "scripts": {
         "test": [
             "@phpstan",
-            "@psalm",
             "@phpunit"
         ],
         "phpunit": "vendor/bin/phpunit",
-        "phpstan": "vendor/bin/phpstan analyse",
+        "phpstan": "vendor/bin/phpstan analyse"
-        "psalm": "vendor/bin/psalm"
     }
 }

examples/wrapping_clock.php

@@ -0,0 +1,28 @@
+<?php
+
+require __DIR__.'/../vendor/autoload.php';
+
+use Beste\Clock\WrappingClock;
+
+// Create a frozen $now so that we can test the wrapping clock.
+$now = new DateTimeImmutable('2012-04-24 12:00:00');
+
+// Create an object that is NOT a clock, but has a now() method returning the frozen $now.
+$clock = new class($now) {
+    private \DateTimeImmutable $now;
+
+    public function __construct(\DateTimeImmutable $now)
+    {
+        $this->now = $now;
+    }
+
+    public function now(): \DateTimeImmutable
+    {
+        return $this->now;
+    }
+};
+
+// We can now wrap the object in a clock.
+$wrappedClock = WrappingClock::wrapping($clock);
+
+assert($now->format(DATE_ATOM) === $wrappedClock->now()->format(DATE_ATOM));

phpstan.neon.dist

@@ -7,5 +7,3 @@ parameters:
 
 	tmpDir: .build/phpstan/
 
-	bootstrapFiles:
-		- ./src/psr-polyfill.php

phpunit.xml.dist

@@ -1,9 +1,9 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.5/phpunit.xsd"
          bootstrap="vendor/autoload.php"
-         cacheResultFile=".build/phpunit/phpunit.cache"
+         cacheDirectory=".build/phpunit/cache"
-         beStrictAboutCoversAnnotation="true"
+         beStrictAboutCoverageMetadata="true"
          colors="true"
 >
     <testsuites>
@@ -12,10 +12,10 @@
         </testsuite>
     </testsuites>
 
-    <coverage>
+    <source>
         <include>
-            <directory>src/Clock</directory>
+            <directory>src</directory>
         </include>
-    </coverage>
+    </source>
 
 </phpunit>

psalm.xml.dist

@@ -1,21 +0,0 @@
-<?xml version="1.0"?>
-<psalm
-    xmlns="https://getpsalm.org/schema/config"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
-    cacheDirectory=".build/psalm"
-    errorLevel="1"
-    resolveFromConfigFile="true"
->
-    <projectFiles>
-        <directory name="src" />
-        <directory name="tests" />
-        <ignoreFiles>
-            <directory name="vendor" />
-        </ignoreFiles>
-    </projectFiles>
-
-    <plugins>
-        <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
-    </plugins>
-</psalm>

src/Clock.php

@@ -1,12 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Beste;
-
-use Psr\Clock\ClockInterface;
-
-interface Clock extends ClockInterface
-{
-
-}

src/FrozenClock.php

@@ -4,12 +4,11 @@ declare(strict_types=1);
 
 namespace Beste\Clock;
 
-use Beste\Clock;
 use DateTimeImmutable;
 use DateTimeZone;
 use Psr\Clock\ClockInterface;
 
-final class FrozenClock implements Clock
+final class FrozenClock implements ClockInterface
 {
     private DateTimeImmutable $frozenAt;
 

src/LocalizedClock.php

@@ -4,13 +4,13 @@ declare(strict_types=1);
 
 namespace Beste\Clock;
 
-use Beste\Clock;
 use DateTimeImmutable;
 use DateTimeZone;
 use InvalidArgumentException;
+use Psr\Clock\ClockInterface;
 use Throwable;
 
-final class LocalizedClock implements Clock
+final class LocalizedClock implements ClockInterface
 {
     private DateTimeZone $timeZone;
 
@@ -19,10 +19,7 @@ final class LocalizedClock implements Clock
         $this->timeZone = $timeZone;
     }
 
-    /**
+    public static function in(DateTimeZone|string $timeZone): self
-     * @param DateTimeZone|string $timeZone
-     */
-    public static function in($timeZone): self
     {
         if (is_string($timeZone)) {
             try {

src/MinuteClock.php

@@ -4,11 +4,10 @@ declare(strict_types=1);
 
 namespace Beste\Clock;
 
-use Beste\Clock;
 use DateTimeImmutable;
 use Psr\Clock\ClockInterface;
 
-final class MinuteClock implements Clock
+final class MinuteClock implements ClockInterface
 {
     private ClockInterface $clock;
 

src/SystemClock.php

@@ -4,10 +4,10 @@ declare(strict_types=1);
 
 namespace Beste\Clock;
 
-use Beste\Clock;
 use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
 
-final class SystemClock implements Clock
+final class SystemClock implements ClockInterface
 {
     private function __construct()
     {

src/UTCClock.php

@@ -4,11 +4,11 @@ declare(strict_types=1);
 
 namespace Beste\Clock;
 
-use Beste\Clock;
 use DateTimeImmutable;
 use DateTimeZone;
+use Psr\Clock\ClockInterface;
 
-final class UTCClock implements Clock
+final class UTCClock implements ClockInterface
 {
     private DateTimeZone $timeZone;
 

src/WrappingClock.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Beste\Clock;
+
+use Closure;
+use DateTimeImmutable;
+use InvalidArgumentException;
+use Psr\Clock\ClockInterface;
+use ReflectionMethod;
+use UnexpectedValueException;
+
+final class WrappingClock implements ClockInterface
+{
+    private ClockInterface $wrappedClock;
+
+    private function __construct(ClockInterface $wrappedClock)
+    {
+        $this->wrappedClock = $wrappedClock;
+    }
+
+    /**
+     * @throws InvalidArgumentException when the given object doesn't behave like a clock.
+     */
+    public static function wrapping(object $clock): self
+    {
+        if ($clock instanceof ClockInterface) {
+            return new self($clock);
+        }
+
+        if (!method_exists($clock, 'now')) {
+            throw new InvalidArgumentException('$clock must implement Psr\Clock\ClockInterface or have a now() method');
+        }
+
+        $method = new ReflectionMethod($clock, 'now');
+
+        if (!$method->isPublic() || $method->getNumberOfRequiredParameters() > 0) {
+            throw new InvalidArgumentException('$clock->now() must be public and accept no required parameters');
+        }
+
+        $wrappedClock = new class($method->getClosure($clock)) implements ClockInterface {
+            private Closure $now;
+
+            public function __construct(Closure $now)
+            {
+                $this->now = $now;
+            }
+
+            public function now(): DateTimeImmutable
+            {
+                $now = ($this->now)();
+
+                if (!$now instanceof DateTimeImmutable) {
+                    throw new UnexpectedValueException('$clock->now() must return a DateTimeImmutable');
+                }
+
+                return $now;
+            }
+        };
+
+        return new self($wrappedClock);
+    }
+
+    public function now(): DateTimeImmutable
+    {
+        return $this->wrappedClock->now();
+    }
+}

src/psr-polyfill.php

@@ -1,17 +0,0 @@
-<?php
-
-namespace Psr\Clock;
-
-if (class_exists('\Psr\Clock\ClockInterface')) {
-    return;
-}
-
-use DateTimeImmutable;
-
-interface ClockInterface
-{
-    /**
-     * Returns the current time as a DateTimeImmutable Object
-     */
-    public function now(): DateTimeImmutable;
-}

tests/FrozenClockTest.php

@@ -6,21 +6,18 @@ namespace Beste\Clock\Tests;
 
 use Beste\Clock\FrozenClock;
 use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use Psr\Clock\ClockInterface;
 
 /**
  * @internal
- * @coversDefaultClass \Beste\Clock\FrozenClock
  */
+#[CoversClass(FrozenClock::class)]
 final class FrozenClockTest extends TestCase
 {
-    /**
+    #[Test]
-     * @test
-     * @covers ::__construct
-     * @covers ::at
-     * @covers ::now
-     */
     public function itFreezesTime(): void
     {
         $now = new DateTimeImmutable('2021-03-21 22:16:00');
@@ -29,14 +26,7 @@ final class FrozenClockTest extends TestCase
         self::assertEquals($now, $clock->now());
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @uses \Beste\Clock\FrozenClock::__construct
-     * @uses \Beste\Clock\FrozenClock::fromUTC()
-     *
-     * @covers ::now()
-     */
     public function itReturnsAnEqualNowButNotTheSame(): void
     {
         $clock = FrozenClock::fromUTC();
@@ -48,14 +38,7 @@ final class FrozenClockTest extends TestCase
         self::assertNotSame($first, $second);
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @uses \Beste\Clock\FrozenClock::__construct
-     * @uses \Beste\Clock\FrozenClock::now
-     *
-     * @covers ::withNowFrom
-     */
     public function itFreezesTimeFromAnotherClock(): void
     {
         $now = new DateTimeImmutable('now');
@@ -71,14 +54,7 @@ final class FrozenClockTest extends TestCase
         self::assertEquals($now, $frozenClock->now());
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @uses \Beste\Clock\FrozenClock::__construct
-     * @uses \Beste\Clock\FrozenClock::now
-     *
-     * @covers ::fromUTC
-     */
     public function itFreezesTheCurrentUTCTime(): void
     {
         $clock = FrozenClock::fromUTC();
@@ -87,15 +63,7 @@ final class FrozenClockTest extends TestCase
         self::assertEquals($clock->now(), $clock->now());
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @uses \Beste\Clock\FrozenClock::__construct
-     * @uses \Beste\Clock\FrozenClock::at
-     * @uses \Beste\Clock\FrozenClock::now
-     *
-     * @covers ::setTo
-     */
     public function itCanBeSet(): void
     {
         $now = new DateTimeImmutable('2021-03-21 18:18:18');

tests/LocalizedClockTest.php

@@ -7,18 +7,17 @@ namespace Beste\Clock\Tests;
 use Beste\Clock\LocalizedClock;
 use DateTimeZone;
 use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 
 /**
  * @internal
- * @coversDefaultClass \Beste\Clock\LocalizedClock
  */
+#[CoversClass(LocalizedClock::class)]
 final class LocalizedClockTest extends TestCase
 {
-    /**
+    #[Test]
-     * @test
-     * @covers ::in
-     */
     public function itRejectsAnInvalidTimeZone(): void
     {
         $this->expectException(InvalidArgumentException::class);
@@ -26,12 +25,7 @@ final class LocalizedClockTest extends TestCase
         LocalizedClock::in('invalid');
     }
 
-    /**
+    #[Test]
-     * @test
-     * @covers ::__construct
-     * @covers ::in
-     * @covers ::now
-     */
     public function itUsesTheGivenTimeZone(): void
     {
         $timeZone = new DateTimeZone('Asia/Bangkok');
@@ -41,12 +35,7 @@ final class LocalizedClockTest extends TestCase
         self::assertSame($timeZone->getName(), $now->getTimezone()->getName());
     }
 
-    /**
+    #[Test]
-     * @test
-     * @covers ::__construct
-     * @covers ::in
-     * @covers ::now
-     */
     public function itAcceptsTheTimeZoneAsAString(): void
     {
         $timeZone = 'Pacific/Guam';

tests/MinuteClockTest.php

@@ -6,30 +6,23 @@ namespace Beste\Clock\Tests;
 
 use Beste\Clock\MinuteClock;
 use DateTimeImmutable;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use Psr\Clock\ClockInterface;
 
 /**
  * @internal
- * @coversDefaultClass \Beste\Clock\MinuteClock
  */
+#[CoversClass(MinuteClock::class)]
 final class MinuteClockTest extends TestCase
 {
-    /**
+    #[Test]
-     * @test
+    #[DataProvider('dateTimeStringProvider')]
-     *
-     * @covers ::__construct
-     * @covers ::wrapping
-     * @covers ::now
-     * @covers ::floor
-     *
-     * @uses \Beste\Clock\FrozenClock
-     *
-     * @dataProvider dateTimeStringProvider
-     */
     public function itDiscardsEverythingSmallerThanMinutes(string $format, string $input, string $expected): void
     {
-        $mockClock = $this->createMock(ClockInterface::class);
+        $mockClock = self::createStub(ClockInterface::class);
         $mockClock->method('now')->willReturn(new DateTimeImmutable($input));
 
         // Just to be sure that the test input is valid ^^
@@ -43,7 +36,7 @@ final class MinuteClockTest extends TestCase
     /**
      * @return array<string, string[]>
      */
-    public function dateTimeStringProvider(): array
+    public static function dateTimeStringProvider(): array
     {
         return [
             'microseconds' => [

tests/SystemClockTest.php

@@ -5,12 +5,14 @@ declare(strict_types=1);
 namespace Beste\Clock\Tests;
 
 use Beste\Clock\SystemClock;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 
 /**
  * @internal
- * @coversDefaultClass \Beste\Clock\SystemClock
  */
+#[CoversClass(SystemClock::class)]
 final class SystemClockTest extends TestCase
 {
     private string $defaultTimeZone;
@@ -25,16 +27,10 @@ final class SystemClockTest extends TestCase
         date_default_timezone_set($this->defaultTimeZone);
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @covers ::__construct
-     * @covers ::create
-     * @covers ::now
-     */
     public function itUsesTheSystemTimeZone(): void
     {
-        $timeZone = 'Europe/Berlin';
+        $timeZone = $this->defaultTimeZone === 'Europe/Berlin' ? 'UTC' : 'Europe/Berlin';
         self::assertNotSame($timeZone, $this->defaultTimeZone);
 
         date_default_timezone_set($timeZone);

tests/UTCClockTest.php

@@ -5,12 +5,14 @@ declare(strict_types=1);
 namespace Beste\Clock\Tests;
 
 use Beste\Clock\UTCClock;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 
 /**
  * @internal
- * @coversDefaultClass \Beste\Clock\UTCClock
  */
+#[CoversClass(UTCClock::class)]
 final class UTCClockTest extends TestCase
 {
     private string $defaultTimeZone;
@@ -25,13 +27,7 @@ final class UTCClockTest extends TestCase
         date_default_timezone_set($this->defaultTimeZone);
     }
 
-    /**
+    #[Test]
-     * @test
-     *
-     * @covers ::__construct
-     * @covers ::create
-     * @covers ::now
-     */
     public function itUsesUTCRegardlessOfTheSystemTimeZone(): void
     {
         date_default_timezone_set('Europe/Berlin');

tests/WrappingClockTest.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Beste\Clock\Tests;
+
+use Beste\Clock\FrozenClock;
+use Beste\Clock\WrappingClock;
+use DateTimeImmutable;
+use DateTimeZone;
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+use UnexpectedValueException;
+
+/**
+ * @internal
+ */
+#[CoversClass(WrappingClock::class)]
+#[UsesClass(FrozenClock::class)]
+final class WrappingClockTest extends TestCase
+{
+    #[Test]
+    public function itWrapsAClockInterface(): void
+    {
+        $clock = FrozenClock::fromUTC();
+
+        $wrappedClock = WrappingClock::wrapping($clock);
+
+        self::assertSame(
+            $clock->now()->format(DATE_ATOM),
+            $wrappedClock->now()->format(DATE_ATOM)
+        );
+    }
+
+    #[Test]
+    public function itWrapsAnObjectWithANowMethod(): void
+    {
+        $now = FrozenClock::fromUTC()->now();
+
+        $clock = new class($now) {
+            private DateTimeImmutable $now;
+
+            public function __construct(DateTimeImmutable $now)
+            {
+                $this->now = $now;
+            }
+
+            public function now(): DateTimeImmutable
+            {
+                return $this->now;
+            }
+        };
+
+        $wrappedClock = WrappingClock::wrapping($clock);
+
+        self::assertSame(
+            $now->format(DATE_ATOM),
+            $wrappedClock->now()->format(DATE_ATOM)
+        );
+    }
+
+    #[Test]
+    public function itDoesNotCallNowWhileWrapping(): void
+    {
+        $clock = new class() {
+            public int $calls = 0;
+
+            public function now(): DateTimeImmutable
+            {
+                ++$this->calls;
+
+                return new DateTimeImmutable();
+            }
+        };
+
+        $wrappedClock = WrappingClock::wrapping($clock);
+
+        self::assertSame(0, $clock->calls);
+
+        $wrappedClock->now();
+
+        self::assertSame(1, $clock->calls);
+    }
+
+    #[Test]
+    public function itRejectsObjectsWithANowMethodReturningANonDateTimeImmutable(): void
+    {
+        $clock = new class() {
+            public function now(): string
+            {
+                return 'foo';
+            }
+        };
+
+        $this->expectException(UnexpectedValueException::class);
+        $this->expectExceptionMessage('$clock->now() must return a DateTimeImmutable');
+
+        WrappingClock::wrapping($clock)->now();
+    }
+
+    #[Test]
+    public function itRejectsObjectsWithoutANowMethod(): void
+    {
+        $clock = new class() {
+        };
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('$clock must implement Psr\Clock\ClockInterface or have a now() method');
+
+        WrappingClock::wrapping($clock);
+    }
+
+    #[Test]
+    public function itRejectsObjectsWithANonPublicNowMethod(): void
+    {
+        $clock = new class() {
+            protected function now(): DateTimeImmutable
+            {
+                return new DateTimeImmutable();
+            }
+        };
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('$clock->now() must be public and accept no required parameters');
+
+        WrappingClock::wrapping($clock);
+    }
+
+    #[Test]
+    public function itRejectsObjectsWithANowMethodRequiringArguments(): void
+    {
+        $clock = new class() {
+            public function now(string $timeZone): DateTimeImmutable
+            {
+                return new DateTimeImmutable('now', new DateTimeZone($timeZone));
+            }
+        };
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('$clock->now() must be public and accept no required parameters');
+
+        WrappingClock::wrapping($clock);
+    }
+}