PHPackages                             jeckel-lab/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. [Testing & Quality](/categories/testing)
4. /
5. jeckel-lab/clock

ActiveLibrary[Testing & Quality](/categories/testing)

jeckel-lab/clock
================

Clock abstraction library

1.2.0(4y ago)14.1k4[1 issues](https://github.com/Jeckel-Lab/clock/issues)[3 PRs](https://github.com/Jeckel-Lab/clock/pulls)2MITPHPPHP ^7.2 || ^8.0CI passing

Since Nov 15Pushed 1y ago1 watchersCompare

[ Source](https://github.com/Jeckel-Lab/clock)[ Packagist](https://packagist.org/packages/jeckel-lab/clock)[ RSS](/packages/jeckel-lab-clock/feed)WikiDiscussions master Synced 5d ago

READMEChangelog (9)Dependencies (9)Versions (12)Used By (2)

[![Latest Stable Version](https://camo.githubusercontent.com/14fe9ce8c1cc96083fcfe70044a75c67b6cb84a1b4085e7f28bbf7874724ea09/68747470733a2f2f706f7365722e707567782e6f72672f6a65636b656c2d6c61622f636c6f636b2f762f737461626c65)](https://packagist.org/packages/jeckel-lab/clock)[![Total Downloads](https://camo.githubusercontent.com/d67657959017a07c0ff9d56f4bea4836c99d17bd8656339ea77fcbc146996fab/68747470733a2f2f706f7365722e707567782e6f72672f6a65636b656c2d6c61622f636c6f636b2f646f776e6c6f616473)](https://packagist.org/packages/jeckel-lab/clock)[![Build Status](https://github.com/jeckel-lab/clock/workflows/validate/badge.svg)](https://github.com/Jeckel-Lab/clock/actions)[![codecov](https://camo.githubusercontent.com/6d514f9e287c2679e200db573468f062a9e99bd24c06d4a1eb931cbd383c4e27/68747470733a2f2f636f6465636f762e696f2f67682f6a65636b656c2d6c61622f636c6f636b2f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/jeckel-lab/clock)

Clock
=====

[](#clock)

A clock abstraction library for PHP which allow to mock system clock when testing

Installation
============

[](#installation)

```
composer require jeckel-lab/clock
```

Usage
-----

[](#usage)

In your code, always use the `JeckelLab\Contract\Infrastructure\System\Clock` interface in your services when you need to access the current time. After that, you just have to define which implementation to use according to your environment (real or fake for tests).

In some framework, it can be easier to use the factory to handle the switch and inject the required configuration.

### Different fake clock

[](#different-fake-clock)

There are 2 types of fake clock available:

- **`frozen`**: This clock with always return the same value everytime we call it
- **`faked`**: This one will return an incremented time (like a real one) but initiated at the beginning at the script with a defined date time. It's useful to continue to keep track of long process.

Fake clock can both be initiate in 2 different ways:

- by passing the value of the initial time (`fake_time_init` value in configuration), This option is useful when you want to always use the same time, or initialize it with an env variable
- by passing the path to a file where it will read the value of time (`fake_time_path`). This option is useful when you want to control the time of each of your process when running different tests cases.

Use with Symfony 4 and 5
------------------------

[](#use-with-symfony-4-and-5)

With SF4 and SF5 we use the internal DI system with the factory. The factory will get different parameters according to the current environment.

Configure DI with a factory in `config/services.yaml`:

```
# config/services.yaml
    JeckelLab\Contract\Infrastructure\System\Clock:
        factory: ['JeckelLab\Clock\Factory\ClockFactory', getClock]
        arguments: ['%clock%']
```

Configure default parameters in `config/packages/parameters.yaml`:

```
# config/packages/parameters.yaml
parameters:
    clock:
        mode: real
        timezone: Europe/Paris  # Optional
```

And then configure parameters for **tests** environment in `config/packages/test/parameters.yaml`:

```
# config/packages/test/parameters.yaml
parameters:
    clock:
        mode: faked
        fake_time_init: '2020-12-11 14:00:00'
```

or

```
# config/packages/test/parameters.yaml
parameters:
    clock:
        mode: frozen
        fake_time_path: '%kernel.project_dir%/var/test/fake_clock'
        fallback_to_current_date: true # Default: false, if true and file is not found or has invalid valid, then fallback to RealClock
```

Test with Codeception
---------------------

[](#test-with-codeception)

To be able to change current date in your Codeception tests, you first need to configure your fake clock to use the `fake_time_path` file as a time source.

Next, configure codeception with the provided helper:

```
# codeception.yaml

# ...
modules:
    config:
        \JeckelLab\Clock\CodeceptionHelper\Clock:
            fake_time_path: 'var/test/fake_clock'   # Required: path where the fake time should be provided to your project
            date_format: 'Y/m/d'  # Optional, date format for date value defined in your tests (default: Y/m/d)
            time_format: 'H:i:s'  # Optional, time format for time value defined in your tests (default: H:i:s)
```

Enable the helper in your suite:

```
# acceptance.suite.yml

actor: AcceptanceTester
modules:
    enabled:
        - \JeckelLab\Clock\CodeceptionHelper\Clock
```

Now you can set the fake time in your tests:

**in BDD:**

```
Feature: A feature description

  Scenario: A scenario description
    Given current date is "2021/03/26" and time is "08:35:00"
```

**in other tests:**

```
/** @var \Codeception\Actor $i */
$I->haveCurrentDateAndTime('2021/03/26', '08:35:00');

// or
$I->haveCurrentDateTime(DateTime::createFromFormat("Y/m/d H:i", "2021/03/26 08:35"));
```

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance12

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 95.7% 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 ~81 days

Recently: every ~39 days

Total

9

Last Release

1720d ago

Major Versions

0.2.0 → v1.0.02020-12-11

PHP version history (3 changes)0.1.0PHP >=7.1

0.2.0PHP >=7.2

v1.0.0PHP ^7.2 || ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/57215536?v=4)[Jeckel-Lab](/maintainers/jeckel-lab)[@Jeckel-Lab](https://github.com/Jeckel-Lab)

---

Top Contributors

[![jeckel](https://avatars.githubusercontent.com/u/2981531?v=4)](https://github.com/jeckel "jeckel (90 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (3 commits)")[![fossabot](https://avatars.githubusercontent.com/u/29791463?v=4)](https://github.com/fossabot "fossabot (1 commits)")

---

Tags

clockmockphpphp-libraryphp8symfony4symfony5testing

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[vimeo/psalm

A static analysis tool for finding errors in PHP applications

5.8k77.5M6.7k](/packages/vimeo-psalm)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)

PHPackages © 2026

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