[Clock] A new component to decouple applications from the system clock

Author: nicolas-grekas

composer.json

@@ -57,6 +57,7 @@
         "symfony/asset": "self.version",
         "symfony/browser-kit": "self.version",
         "symfony/cache": "self.version",
+        "symfony/clock": "self.version",
         "symfony/config": "self.version",
         "symfony/console": "self.version",
         "symfony/css-selector": "self.version",

src/Symfony/Component/Clock/.gitattributes

@@ -0,0 +1,4 @@
+/Tests export-ignore
+/phpunit.xml.dist export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/Symfony/Component/Clock/.gitignore

@@ -0,0 +1,3 @@
+vendor/
+composer.lock
+phpunit.xml

src/Symfony/Component/Clock/CHANGELOG.md

@@ -0,0 +1,7 @@
+CHANGELOG
+=========
+
+6.2
+---
+
+ * Add the component

src/Symfony/Component/Clock/HrClock.php

@@ -0,0 +1,83 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock;
+
+/**
+ * A high-resolution monotonic clock, counting from an arbitrary point in time.
+ *
+ * @author Nicolas Grekas <[email protected]>
+ */
+final class HrClock implements TimeInterface
+{
+    private \DateTimeZone $timezone;
+
+    public function __construct(\DateTimeZone|string $timezone = null)
+    {
+        if (false === hrtime()) {
+            throw new \LogicException('hrtime() returned false: the runtime environment does not provide access to high-resolution time.');
+        }
+
+        if (\is_string($timezone ??= date_default_timezone_get())) {
+            $this->timezone = new \DateTimeZone($timezone);
+        } else {
+            $this->timezone = $timezone;
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function now(): \DateTimeImmutable
+    {
+        $hrtime = hrtime();
+        $now = '@'.$hrtime[0].'.'.substr(str_pad($hrtime[1], 9, 0, \STR_PAD_LEFT), 0, -3);
+
+        return (new \DateTimeImmutable($now, $this->timezone))->setTimezone($this->timezone);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeArray(): array
+    {
+        $now = hrtime();
+
+        return [$now[0], (float) ($now[1] / 1E3)];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeFloat(): float
+    {
+        return hrtime(true) / 1E9;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeInt(): int
+    {
+        return hrtime()[0];
+    }
+
+    public function sleep(float|int $seconds): void
+    {
+        if (0 < $s = (int) $seconds) {
+            sleep($s);
+        }
+
+        if (0 < $us = $seconds - $s) {
+            usleep($us * 1E6);
+        }
+    }
+}

src/Symfony/Component/Clock/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2022 Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

src/Symfony/Component/Clock/MockClock.php

@@ -0,0 +1,91 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock;
+
+/**
+ * A clock that always returns the same date, suitable for testing time-sensitive logic.
+ *
+ * @author Nicolas Grekas <[email protected]>
+ */
+final class MockClock implements TimeInterface
+{
+    private \DateTimeImmutable $now;
+
+    public function __construct(\DateTimeImmutable|\DateTimeZone|string $now = null)
+    {
+        if (\is_string($now ??= 'UTC')) {
+            try {
+                $now = new \DateTimeZone($now);
+            } catch (\Exception) {
+                $now = new \DateTimeImmutable($now);
+            }
+        }
+
+        $this->now = $now instanceof \DateTimeImmutable ? $now : new \DateTimeImmutable('now', $now);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function now(): \DateTimeImmutable
+    {
+        return clone $this->now;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeArray(): array
+    {
+        $now = explode('.', $this->now->format('U.u'));
+
+        return [(int) $now[0], (float) $now[1]];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeFloat(): float
+    {
+        return (float) $this->now->format('U.u');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeInt(): int
+    {
+        return $this->now->getTimestamp();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function sleep(float|int $seconds): void
+    {
+        $now = explode('.', $this->now->format('U.u'));
+
+        if (0 < $s = (int) $seconds) {
+            $now[0] += $s;
+        }
+
+        if (0 < ($us = $seconds - $s) && 1E6 <= $now[1] += $us * 1E6) {
+            ++$now[0];
+            $now[1] -= 1E6;
+        }
+
+        $datetime = '@'.$now[0].'.'.str_pad($now[1], 6, 0, \STR_PAD_LEFT);
+        $timezone = $this->now->getTimezone();
+
+        $this->now = (new \DateTimeImmutable($datetime, $timezone))->setTimezone($timezone);
+    }
+}

src/Symfony/Component/Clock/NativeClock.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Clock;
+
+/**
+ * A clock that returns the system time.
+ *
+ * @author Nicolas Grekas <[email protected]>
+ */
+final class NativeClock implements TimeInterface
+{
+    private \DateTimeZone $timezone;
+
+    public function __construct(\DateTimeZone|string $timezone = null)
+    {
+        if (\is_string($timezone ??= date_default_timezone_get())) {
+            $this->timezone = new \DateTimeZone($timezone);
+        } else {
+            $this->timezone = $timezone;
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function now(): \DateTimeImmutable
+    {
+        return new \DateTimeImmutable('now', $this->timezone);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeArray(): array
+    {
+        $now = gettimeofday();
+
+        return [$now['sec'], (float) $now['usec']];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeFloat(): float
+    {
+        return microtime(true);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function timeInt(): int
+    {
+        return time();
+    }
+
+    public function sleep(float|int $seconds): void
+    {
+        if (0 < $s = (int) $seconds) {
+            sleep($s);
+        }
+
+        if (0 < $us = $seconds - $s) {
+            usleep($us * 1E6);
+        }
+    }
+}

src/Symfony/Component/Clock/README.md

@@ -0,0 +1,48 @@
+Clock Component
+===============
+
+Symfony Clock enables decoupling applications from the system clock.
+
+Getting Started
+---------------
+
+```
+$ composer require symfony/clock
+```
+
+```php
+use Symfony\Component\Clock\NativeClock;
+use Symfony\Component\Clock\TimeInterface;
+
+class MyClockSensitiveClass
+{
+    public function __construct(
+        private TimeInterface $clock,
+    ) {
+    }
+
+    public function doSomething()
+    {
+        $now = $this->clock->now();
+        // [...] do something with $now, which is a \DateTimeImmutable object
+
+        $this->clock->sleep(1);    // Pause execution for 1 second
+        $this->clock->timeInt();   // Gets the current timestamp with second precision
+        $this->clock->timeFloat(); // Gets the current timestamp with sub-second precision
+        $this->clock->timeArray(); // Gets the current timestamp with sub-second precision and 32-bit portability
+    }
+}
+
+$clock = new NativeClock();
+$service = new MyClockSensitiveClass($clock);
+$service->doSomething();
+```
+
+Resources
+---------
+
+ * [Documentation](https://symfony.com/doc/current/clock.html)
+ * [Contributing](https://symfony.com/doc/current/contributing/index.html)
+ * [Report issues](https://github.com/symfony/symfony/issues) and
+   [send Pull Requests](https://github.com/symfony/symfony/pulls)
+   in the [main Symfony repository](https://github.com/symfony/symfony)