PHPackages                             vulpes/clock - 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. [PSR & Standards](/categories/psr-standards)
4. /
5. vulpes/clock

ActiveLibrary[PSR & Standards](/categories/psr-standards)

vulpes/clock
============

PHP FIG PSR-20 Clock implementation.

v1.0(3y ago)0841MITPHPPHP >=8.1

Since May 12Pushed 3y ago1 watchersCompare

[ Source](https://github.com/ahtreuw/clock)[ Packagist](https://packagist.org/packages/vulpes/clock)[ RSS](/packages/vulpes-clock/feed)WikiDiscussions main Synced 3w ago

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

Clock
=====

[](#clock)

This repository contains the [PHP FIG PSR-20](https://www.php-fig.org/psr/psr-20/) Clock implementation.

Install
-------

[](#install)

Via Composer Package is available on [Packagist](http://packagist.org/packages/vulpes/clock), you can install it using [Composer](http://getcomposer.org).

```
$ composer require vulpes/clock
```

Details
-------

[](#details)

`Clock\Clock` and `Clock\FrozenClock` are instance of `Clock\ClockInterface` and `Psr\Clock\ClockInterface`.

### Clock

[](#clock-1)

The clock works from a dateTime string (default: `now`), so it can take any value that `strtotime()` can handle,
and that `DateTimeImmutable` in its constructor can handle when calling `Clock::now()` function.

### FrozenClock

[](#frozenclock)

The FrozenClock works from a `DateTimeImmutable` object, so its value never changes,
it will always return the same value within a timezone when calling the `FrozenClock::now()` function.

### Usage

[](#usage)

```
use Clock\ClockInterface;
use Clock\ClockExceptionInterface;
use Clock\Clock;
use Clock\FrozenClock;

// with default parameters, the `Clock::dateTime` parameter will
// always be interpreted as a string
$clock = new Clock(
    /* DateTimeInterface|string|int */ dateTime: ClockInterface::NOW,
    /* DateTimeZone|string */          timeZone: ClockInterface::UTC
);

// with default parameters, the `FrozenClock::dateTime` parameter will
// always be interpreted as a DateTimeImmutable object
$clock = new FrozenClock(
    /* DateTimeInterface|string|int|null */ dateTime:
    new DateTimeImmutable(
        datetime: ClockInterface::NOW,
        timezone: new DateTimeZone(ClockInterface::UTC)
    )
);

// Clock and FrozenClock are identical in behavior below in this section

$clock->now() // DateTimeImmutable
$clock->now()->format('P'); // +01:00
$clock->now()->getTimezone()->getName(); // UTC

// Clock used UTC default, so here $clock will be the same as $utcClock
$utcClock = $clock->withUTC();
$utcClock->now()->getTimezone()->getName() // UTC

$systemTimezoneClock = $clock->withSystemTimezone();
$systemTimezoneClock->now()->getTimezone()->getName() // (system-timezone)

$withCustomTZ = $clock->withDateTimeZone('Europe/Vatican');
$withCustomTZ = $clock->withDateTimeZone(new DateTimeZone('Europe/Vatican'));
$withCustomTZ->now()->getTimezone()->getName() // Europe/Vatican

$with = $clock->with(new DateTime("1989-01-13"));
// $with->now()->format("Y-m-d") > "1989-01-13"

$with = $clock->with(new DateTimeImmutable("2011-01-13"));
// $with->now()->format("Y-m-d") > "2011-01-13"

$with = $clock->with('2022-02-02');
// $with->now()->format("Y-m-d") >  "2022-02-02"

$with = $clock->with(1643756400);
// $with->now()->format("Y-m-d") > ~"2022-02-02"

$with = $clock->with(1111111111);
// $with->now()->getTimestamp() > 1111111111

$withCustomTZ = $clock->withDateTimeZone(new DateTimeZone('Europe/Vatican'));
$withCustomTZ->now()->getTimezone()->getName() // Europe/Vatican

try {
    $clock = new Clock(dateTime: 'unknown-or-bad-timezone');
    $clock->now();
    // ...
} catch (ClockExceptionInterface) {
    // Failed to parse time string...
}

try {
    $clock = new Clock(timeZone: 'bad-timezone');
} catch (ClockExceptionInterface) {
    // Unknown or bad timezone (unknown datetime zone: "bad-timezone")
}
```

### Differences between Clock and FrozenClock in usage

[](#differences-between-clock-and-frozenclock-in-usage)

```
use Clock\Clock;
use Clock\FrozenClock;

$systemClock = new Clock('now');
$frozenClock = new FrozenClock('now');

$systemClock->now()->format('i:s') // 10:02
$frozenClock->now()->format('i:s') // 10:02

// five minutes and 30 seconds later
$systemClock->now()->format('i:s') // 15:32
$frozenClock->now()->format('i:s') // 10:02

// BUT if you set Clock::dateTime with a timestamp, it will retain
// its value as a string from then on and behave like FrozenClock.
$frozenSystemClock = $systemClock->with($frozenClock)
$frozenSystemClockc // 10:02

// The clock works from a dateTime string (default: `now`), so it
// can take any value that `strtotime()` can handle, and that
// `DateTimeImmutable` in its constructor can handle when calling
// `Clock::now()` function.

$alwaysTomorrow = $systemClock->with('+1 day'); // on 2021-01-01
$alwaysTomorrow->now()->format('Y-m-d') // 2021-01-02

// two days later (on 2021-01-03) - sleep(60 * 60 * 24 * 2)
$alwaysTomorrow->now()->format('Y-m-d') // 2021-01-04
```

###  Health Score

25

—

LowBetter than 36% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 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

1138d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/27835865?v=4)[vulpes](/maintainers/vulpes)[@Vulpes](https://github.com/Vulpes)

---

Top Contributors

[![wuertha](https://avatars.githubusercontent.com/u/16253461?v=4)](https://github.com/wuertha "wuertha (3 commits)")

---

Tags

psrclockpsr-20system-clock

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/vulpes-clock/health.svg)

```
[![Health](https://phpackages.com/badges/vulpes-clock/health.svg)](https://phpackages.com/packages/vulpes-clock)
```

###  Alternatives

[psr/clock

Common interface for reading the clock.

644362.7M474](/packages/psr-clock)[psr/container

Common Container Interface (PHP FIG PSR-11)

10.0k1.0B4.4k](/packages/psr-container)[symfony/clock

Decouples applications from the system clock

434192.7M336](/packages/symfony-clock)[stella-maris/clock

A pre-release of the proposed PSR-20 Clock-Interface

7949.0M2](/packages/stella-maris-clock)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[beste/clock

A collection of Clock implementations

7426.0M26](/packages/beste-clock)

PHPackages © 2026

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