barretstorck / tempus-machina
A PSR-20 compliant PHP clock library
Requires
- psr/clock: ^1.0
Requires (Dev)
- phpunit/phpunit: ^10
- squizlabs/php_codesniffer: ^3.0
Provides
README
_____ __ __ _ _
|_ _|__ _ __ ___ _ __ _ _ ___ | \/ | __ _ ___| |__ (_)_ __ __ _
| |/ _ \ '_ ` _ \| '_ \| | | / __| | |\/| |/ _` |/ __| '_ \| | '_ \ / _` |
| | __/ | | | | | |_) | |_| \__ \ | | | | (_| | (__| | | | | | | | (_| |
|_|\___|_| |_| |_| .__/ \__,_|___/ |_| |_|\__,_|\___|_| |_|_|_| |_|\__,_|
|_|
(Latin for Time Machine)
Tempus Machina is a PSR-20 compliant
Clock library. It's purpose is to allow developers to treat time as a dependency
that can be passed into code, and therefore mocked for testing, instead of
relying on hard coded calls to time()
and similar functions.
Have you ever wanted to make sure your code runs as expected during a daylight savings time transition? What about if the date is February 29th? Or what if there is a leap second? With Tempus Machina you can simulate these scenarios in your test environments.
View on Packagist.org.
Setup
To add Tempus Machina to your project run:
composer require barretstorck/tempus-machina
Available Clocks
There are 3 Clocks that implement Psr\Clock\ClockInterface
and are packaged
with Tempus Machina:
1. SystemClock
The SystemClock is the default clock and always returns the device's real system
timestamp. Anything that uses the UsesClockTrait
trait will automatically use
the SystemClock by default if no other clocks are given.
$clock = new \BarretStorck\TempusMachina\SystemClock(); $now = $clock->now(); // Returns a DateTimeImmutable object for the system's current time. $timestamp = $now->getTimestamp(); // Returns the system's current Unix timestamp.
2. FrozenClock
The FrozenClock will always provide whatever timestamp it is last given and will not move forward in time. If no timestamp is given then the system's current time will be used by default.
The FrozenClock constructor and set()
function can accept any of the following
parameters:
- An integer unix timestamp
- A DateTime formatted string
- An existing DateTimeInterface object
- An existing ClockInterface object
- null or no parameters to use the current system timestamp as a default
// Simulate February 29th 2024. $clock = new \BarretStorck\TempusMachina\FrozenClock('February 29th 2024'); $now1 = $clock->now(); sleep(10); // Wait 10 seconds in real time. $now2 = $clock->now(); // $now2 is still equal to $now1. // Simulate February 29th 2124. $clock->set(4864860000);
3. OffsetClock
The OffsetClock will continue to move forward in real time from whatever timestamp it is last given. If no timestamp is given then the system's current time will be used by default.
The OffsetClock constructor and set()
function can accept any of the following
parameters:
- An integer unix timestamp
- A DateInterval formatted string
- A DateTime formatted string
- An existing DateTimeInterface object
- An existing ClockInterface object
- An existing DateInterval object
- null or no parameters to use the current system timestamp as a default
// Simulate March 9th 2025 at 23:59:59 just before daylight savings time begins $clock = new \BarretStorck\TempusMachina\OffsetClock('2025-03-25T23:59:59+00:00'); echo $clock->now()->format(\DateTimeInterface::RFC3339); // Will echo "2025-03-25T23:59:59+00:00" sleep(10); // Wait 10 seconds to allow for real time to pass. echo $clock->now()->format(\DateTimeInterface::RFC3339); // Will echo "2025-03-26T01:09:00+00:00"
Example code
use Psr\Clock\ClockInterface; use BarretStorck\TempusMachina\{UsesClockInterface, UsesClockTrait}; class MyObject implements UsesClockInterface { use UsesClockTrait; public function __construct(null|ClockInterface $clock = null) { // If $clock is null, then the real time SystemClock will be available // by default for any future calls of `getClock()`. $this->setClock($clock); } public function doSomething() { // No longer hard coding `time()` or `new DateTimeImmutable('now')` calls. //$now = time(); //$now = new DateTimeImmutable('now'); // The clock is now available and can be mocked in testing by providing // a FrozenClock or OffsetClock to the MyObject constructor or it's // `setClock()` function. $now = $this->getClock()->now(); } }