PHPackages                             barretstorck/tempus-machina - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. barretstorck/tempus-machina

ActiveLibrary[Utility & Helpers](/categories/utility)

barretstorck/tempus-machina
===========================

A PSR-20 compliant PHP clock library

v1.0(1y ago)13MITPHP

Since Jan 3Pushed 1y ago1 watchersCompare

[ Source](https://github.com/barretstorck/tempus-machina)[ Packagist](https://packagist.org/packages/barretstorck/tempus-machina)[ RSS](/packages/barretstorck-tempus-machina/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

```
  _____                                __  __            _     _
 |_   _|__ _ __ ___  _ __  _   _ ___  |  \/  | __ _  ___| |__ (_)_ __   __ _
   | |/ _ \ '_ ` _ \| '_ \| | | / __| | |\/| |/ _` |/ __| '_ \| | '_ \ / _` |
   | |  __/ | | | | | |_) | |_| \__ \ | |  | | (_| | (__| | | | | | | | (_| |
   |_|\___|_| |_| |_| .__/ \__,_|___/ |_|  |_|\__,_|\___|_| |_|_|_| |_|\__,_|
                    |_|

 (Latin for Time Machine)

```

**Tempus Machina** is a [PSR-20](https://www.php-fig.org/psr/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](https://en.wikipedia.org/wiki/Leap_second)? With Tempus Machina you can simulate these scenarios in your test environments.

View on [Packagist.org](https://packagist.org/packages/barretstorck/tempus-machina).

Setup
=====

[](#setup)

To add Tempus Machina to your project run:

```
composer require barretstorck/tempus-machina
```

Available Clocks
================

[](#available-clocks)

There are 3 Clocks that implement `Psr\Clock\ClockInterface` and are packaged with Tempus Machina:

### 1. SystemClock

[](#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

[](#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](https://www.php.net/manual/en/datetime.construct.php) 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

[](#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](https://www.php.net/manual/en/dateinterval.construct.php) string
- A [DateTime formatted](https://www.php.net/manual/en/datetime.construct.php) 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
============

[](#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();
    }
}
```

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance43

Moderate activity, may be stable

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

495d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/774caed0ed52c9bb9b4d27d80090726e1d38de9a592f7dd465dd57324ea46264?d=identicon)[barretstorck](/maintainers/barretstorck)

---

Top Contributors

[![barretstorck](https://avatars.githubusercontent.com/u/113543095?v=4)](https://github.com/barretstorck "barretstorck (19 commits)")

---

Tags

clockpsr20psr-20timetimestamp

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/barretstorck-tempus-machina/health.svg)

```
[![Health](https://phpackages.com/badges/barretstorck-tempus-machina/health.svg)](https://phpackages.com/packages/barretstorck-tempus-machina)
```

###  Alternatives

[symfony/clock

Decouples applications from the system clock

430168.9M205](/packages/symfony-clock)[beste/clock

A collection of Clock implementations

7423.3M20](/packages/beste-clock)[icecave/chrono

A date & time library that is decoupled from the system clock.

54188.9k7](/packages/icecave-chrono)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)