PHPackages                             beste/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. [Utility & Helpers](/categories/utility)
4. /
5. beste/clock

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

beste/clock
===========

A collection of Clock implementations

3.0.0(3y ago)7426.0M↓42.1%117MITPHPPHP ^8.0CI passing

Since Dec 10Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/beste/clock)[ Packagist](https://packagist.org/packages/beste/clock)[ GitHub Sponsors](https://github.com/jeromegamez)[ RSS](/packages/beste-clock/feed)WikiDiscussions 3.x Synced 1w ago

READMEChangelog (7)Dependencies (8)Versions (11)Used By (17)

Clock
=====

[](#clock)

[![Current version](https://camo.githubusercontent.com/37ae0388e6f3fbc9cc8d0ca7fe1f000d124532dad230015e557f4ee4026e30e2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62657374652f636c6f636b2e7376673f6c6f676f3d636f6d706f736572)](https://packagist.org/packages/beste/clock)[![Packagist PHP Version Support](https://camo.githubusercontent.com/72dc2c100d42cbe592d5ec6a5de4ce1835fa3409916413b20fe8e529f936198b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f62657374652f636c6f636b)](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 [PSR-20](https://www.php-fig.org/psr/psr-20/) Clock implementations.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Clocks](#clocks)
    - [`SystemClock`](#systemclock) - Time, as your computer (k)nows it
    - [`LocalizedClock`](#localizedclock) - A clock in a(nother) time zone
    - [`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
------------

[](#installation)

```
composer require beste/clock
```

Clocks
------

[](#clocks)

### `SystemClock`

[](#systemclock)

A System Clock will return a time just as if you would use `new DateTimeImmutable()`. The time zone of the returned value is determined by the clock's environment, for example by the time zone that has been configured in your application, by a previously used `date_default_timezone_set()` or by the value of `date.timezone` in the `php.ini`. If none of these are explicitly set, it uses the `UTC` timezone.

```
# examples/system_clock.php

use Beste\Clock\SystemClock;

$clock = SystemClock::create();

printf("On your system, the current date and time is %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));

date_default_timezone_set('America/Los_Angeles');

printf("Now it's %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));

date_default_timezone_set('Europe/Berlin');

printf("Now it's %s\n", $clock->now()->format('Y-m-d H:i:s T (P)'));
```

### `LocalizedClock`

[](#localizedclock)

A localized clock is aware of the time zone in which it is located. While the time zone of the `SystemClock` is determined from the environment (your PHP configuration), this clock uses the time zone that you initialize it with.

```
# examples/localized_clock.php

use Beste\Clock\LocalizedClock;

$berlin = LocalizedClock::in('Europe/Berlin');
$denver = LocalizedClock::in(new DateTimeZone('America/Denver'));

printf("Berlin: %s\n", $berlin->now()->format('Y-m-d H:i:s T (P)'));
printf("Denver: %s\n", $denver->now()->format('Y-m-d H:i:s T (P)'));
```

### `UTCClock`

[](#utcclock)

`UTC` is the abbreviation for [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)and a special kind of time zone that is not affected by daylight saving time. It is commonly used for the communication of time across different systems (e.g. between your PHP application and a database, or between a backend and a frontend). An `UTCClock` instance behaves exactly the same as an instance of `LocalizedClock::in('UTC')`.

```
# examples/utc_clock.php

use Beste\Clock\UTCClock;

$clock = UTCClock::create();

$anotherTimeZone = 'Africa/Casablanca';

date_default_timezone_set($anotherTimeZone);

printf("The system time zone is %s.\n", $anotherTimeZone);
printf("The clock's time zone is %s.\n", $clock->now()->getTimezone()->getName());
```

### `FrozenClock`

[](#frozenclock)

A frozen clock doesn't move - the time we set it with will stay the same... unless we change it. That makes the frozen clock perfect for testing the behaviour of your time-based use cases, for example in Unit Tests.

```
# examples/frozen_clock.php

use Beste\Clock\FrozenClock;
use Beste\Clock\SystemClock;

$frozenClock = FrozenClock::withNowFrom(SystemClock::create());

printf("\nThe clock is frozen at %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));
printf("\nLet's wait a second…");
sleep(1);
printf("\nIt's one second later, but the clock is still frozen at %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));

$frozenClock->setTo($frozenClock->now()->modify('-5 minutes'));
printf("\nAfter turning back the clock 5 minutes, it's %s", $frozenClock->now()->format('Y-m-d H:i:s T (P)'));
```

### `MinuteClock`

[](#minuteclock)

In some cases, microseconds, milliseconds, or even seconds are too precise for some use cases - sometimes it's just enough if something happened in the same minute. Using the minute

```
# examples/minute_clock.php

use Beste\Clock\FrozenClock;
use Beste\Clock\MinuteClock;

$frozenClock = FrozenClock::at(new DateTimeImmutable('01:23:45'));
$clock = MinuteClock::wrapping($frozenClock);

printf("For %s, the minute clock returns %s\n",
    $frozenClock->now()->format('H:i:s'),
    $clock->now()->format('H:i:s')
);

$frozenClock->setTo($frozenClock->now()->modify('+10 seconds')); // 01:23:55

printf("For %s, the minute clock still returns %s\n",
    $frozenClock->now()->format('H:i:s'),
    $clock->now()->format('H:i:s')
);
```

### `WrappingClock`

[](#wrappingclock)

If you already have an object with a `now()` method returning a `DateTimeImmutable` object, you can wrap it in a `WrappingClock` to make it a "real" Clock.

as a "real" clock.

```
# 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
-------------

[](#running-tests)

```
composer test
```

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance61

Regular maintenance activity

Popularity60

Solid adoption and visibility

Community24

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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

Every ~178 days

Recently: every ~314 days

Total

10

Last Release

36d ago

Major Versions

1.x-dev → 2.0.02022-04-20

2.x-dev → 3.0.02022-11-26

PHP version history (3 changes)1.0.0PHP ~7.4.0 || ~8.0.0 || ~8.1.0

2.2.0PHP ~8.1.0 || ~8.2.0

2.3.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/8685cf532053a084f1eade7b7da00a512c02676e65f1f1bdec73d4978030a47d?d=identicon)[jeromegamez](/maintainers/jeromegamez)

---

Top Contributors

[![jeromegamez](https://avatars.githubusercontent.com/u/67554?v=4)](https://github.com/jeromegamez "jeromegamez (26 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (21 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (21 commits)")[![heiglandreas](https://avatars.githubusercontent.com/u/91998?v=4)](https://github.com/heiglandreas "heiglandreas (1 commits)")

---

Tags

besteclockphppsr-20clockpsr20psr-20clock-interface

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[symfony/clock

Decouples applications from the system clock

432192.7M336](/packages/symfony-clock)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

562565.8k41](/packages/ecotone-ecotone)[eventsauce/eventsauce

A pragmatic event sourcing library for PHP with a focus on developer experience.

8642.2M57](/packages/eventsauce-eventsauce)[flow-php/etl

PHP ETL - Extract Transform Load - Abstraction

377559.7k85](/packages/flow-php-etl)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[stella-maris/clock

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

7949.0M2](/packages/stella-maris-clock)

PHPackages © 2026

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