PHPackages                             lendable/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. lendable/clock

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

lendable/clock
==============

Clock Abstraction

4.4.0(5mo ago)17278.8k↓10.9%3[3 PRs](https://github.com/Lendable/clock/pulls)MITPHPPHP >=8.3CI passing

Since Dec 27Pushed 2w ago34 watchersCompare

[ Source](https://github.com/Lendable/clock)[ Packagist](https://packagist.org/packages/lendable/clock)[ RSS](/packages/lendable-clock/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (15)Versions (30)Used By (0)

Lendable Clock
==============

[](#lendable-clock)

[![Latest Stable Version](https://camo.githubusercontent.com/4156a38710537f71e6a071fe66197b93069daf91b7d7a8967bf0002765cd1632/68747470733a2f2f706f7365722e707567782e6f72672f6c656e6461626c652f636c6f636b2f762f737461626c65)](https://packagist.org/packages/lendable/clock)[![License](https://camo.githubusercontent.com/7b48c68aef894ffaf1f81da9017aee86dcf1386171079b8966ef51ec08570081/68747470733a2f2f706f7365722e707567782e6f72672f6c656e6461626c652f636c6f636b2f6c6963656e7365)](https://packagist.org/packages/lendable/clock)

The Lendable Clock library provides an object-oriented interface for accessing the system time in PHP. While PHP offers direct instantiation of `\DateTime`, and `\DateTimeImmutable` to obtain the current system time, this library introduces the concept of a Clock to offer greater control and flexibility over time-related operations.

Why Use a Clock?
----------------

[](#why-use-a-clock)

You might wonder why you need a clock when you can simply instantiate `\DateTime` objects whenever you need them. Here's why a Clock abstraction is beneficial:

- **Control Over Time**: By depending on a Clock rather than instantiating time objects directly, you gain the ability to reason about and control time within your application.
- **Testing Flexibility**: Using a Clock allows you to swap underlying implementations, making it easier to test time-dependent code. You can stub time with fixed values, simulate time passing, and observe interactions with the Clock for more robust testing.
- **Dependency Management**: Clear dependencies on the Clock class help in managing components that rely on accessing the current system time.
- **PSR-20 Compatibility**: The library aligns with [PSR-20](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-20-clock-meta.md), offering interoperability with other libraries and frameworks.

Installation
------------

[](#installation)

You can install the Lendable Clock library via [Composer](https://getcomposer.org/).

```
composer require lendable/clock
```

Clock Types
-----------

[](#clock-types)

The library provides several types of Clocks to suit different use cases:

### `SystemClock`

[](#systemclock)

- **Target**: Runtime
- **Description**: Delegates to PHP for the current system time, using a fixed timezone at construction.

### `FixedClock`

[](#fixedclock)

- **Target**: Unit/Functional Tests
- **Description**: Always provides a specific timestamp provided at construction, facilitating deterministic testing.

```
$clock = new FixedClock(new \DateTimeImmutable('2024-03-01 14:19:41'));

echo $clock->now()->format('Y-m-d H:i:s'), "\n";
sleep(5);
echo $clock->now()->format('Y-m-d H:i:s'), "\n";
```

```
2024-03-01 14:19:41
2024-03-01 14:19:41

```

### `TickingMockClock`

[](#tickingmockclock)

- **Target**: Unit/Functional Tests
- **Description**: Mocks time starting from a given timestamp and simulates time progressing from that point. Useful for testing time-dependent functionality.

```
$clock = TickingMockClock::tickingFromCurrentTime(new \DateTimeImmutable('2024-03-01 14:19:41'));

echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";
sleep(5);
echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";
```

```
2024-03-01 14:19:41.000006
2024-03-01 14:19:46.005175

```

### `PersistedFixedClock`

[](#persistedfixedclock)

- **Target**: Functional Tests (e.g., Behat vs. Symfony Kernel)
- **Description**: Similar to `FixedClock`, but can persist and load the given timestamp from disk. Ideal for scenarios where you need to reload your context during testing.

Use `PersistedFixedClock::initializeWith(...)` to set up the timestamp and `PersistedFixedClock::fromPersisted(...)` to load from the persisted value on disk.

By leveraging these Clock types, you can enhance the reliability, testability, and maintainability of your time-dependent PHP applications.

```
$clock = PersistedFixedClock::initializeWith(
    __DIR__,
    new FixedFileNameGenerator('time.json'),
    new \DateTimeImmutable('2024-03-01 14:19:41'),
);

echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";

sleep(5);

$clock = PersistedFixedClock::fromPersisted(__DIR__, new FixedFileNameGenerator('time.json'));

echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";
```

```
2024-03-01 14:19:41.000000
2024-03-01 14:19:41.000000

```

###  Health Score

64

—

FairBetter than 99% of packages

Maintenance86

Actively maintained with recent releases

Popularity43

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity87

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 69.9% 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

Every ~122 days

Total

22

Last Release

152d ago

Major Versions

0.1.2 → 1.0.02019-11-06

1.1.0 → 2.0.02021-07-30

2.6.0 → 3.0.02024-07-02

3.2.0 → 4.0.02024-08-20

PHP version history (6 changes)0.1.0PHP >=7.2

1.1.0PHP >=7.4

2.1.0PHP >=8.0

v2.4.0PHP >=8.1

v2.5.0PHP >=8.2

4.4.0PHP >=8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/893f1dc6753940f80d1fe2e9a90db68961bb7f16eab85d6a868e7aecccf8de13?d=identicon)[ben-challis](/maintainers/ben-challis)

---

Top Contributors

[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (720 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (184 commits)")[![ben-challis](https://avatars.githubusercontent.com/u/8275163?v=4)](https://github.com/ben-challis "ben-challis (78 commits)")[![marmichalski](https://avatars.githubusercontent.com/u/57528542?v=4)](https://github.com/marmichalski "marmichalski (24 commits)")[![lendabot[bot]](https://avatars.githubusercontent.com/u/10513749?v=4)](https://github.com/lendabot[bot] "lendabot[bot] (8 commits)")[![jan-j](https://avatars.githubusercontent.com/u/3267115?v=4)](https://github.com/jan-j "jan-j (4 commits)")[![martin-georgiev](https://avatars.githubusercontent.com/u/4849482?v=4)](https://github.com/martin-georgiev "martin-georgiev (3 commits)")[![velkovb](https://avatars.githubusercontent.com/u/10958657?v=4)](https://github.com/velkovb "velkovb (1 commits)")[![AlexisColes](https://avatars.githubusercontent.com/u/8488871?v=4)](https://github.com/AlexisColes "AlexisColes (1 commits)")[![X-Coder264](https://avatars.githubusercontent.com/u/12602463?v=4)](https://github.com/X-Coder264 "X-Coder264 (1 commits)")[![kunicmarko20](https://avatars.githubusercontent.com/u/13528674?v=4)](https://github.com/kunicmarko20 "kunicmarko20 (1 commits)")[![maks-rafalko](https://avatars.githubusercontent.com/u/3725595?v=4)](https://github.com/maks-rafalko "maks-rafalko (1 commits)")[![mannion007](https://avatars.githubusercontent.com/u/5822816?v=4)](https://github.com/mannion007 "mannion007 (1 commits)")[![mateuszsip](https://avatars.githubusercontent.com/u/1377075?v=4)](https://github.com/mateuszsip "mateuszsip (1 commits)")[![Sam-Burns](https://avatars.githubusercontent.com/u/6594039?v=4)](https://github.com/Sam-Burns "Sam-Burns (1 commits)")[![toniperic](https://avatars.githubusercontent.com/u/5714104?v=4)](https://github.com/toniperic "toniperic (1 commits)")

---

Tags

clockmockphppsr-20

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k86.9M2.2k](/packages/symfony-symfony)[symfony/clock

Decouples applications from the system clock

433192.7M336](/packages/symfony-clock)[lcobucci/clock

Yet another clock abstraction

799201.8M146](/packages/lcobucci-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)

PHPackages © 2026

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