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

ActiveLibrary

recruiterphp/clock
==================

Clock and Date library created before PSR alternative existed

v5.1.0(7mo ago)03.2k↓100%1MITPHPPHP ^8.4

Since Mar 28Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/recruiterphp/clock)[ Packagist](https://packagist.org/packages/recruiterphp/clock)[ RSS](/packages/recruiterphp-clock/feed)WikiDiscussions main Synced today

READMEChangelog (5)Dependencies (6)Versions (12)Used By (1)

Recruiter\\Clock
================

[](#recruiterclock)

A comprehensive clock and date/time library for PHP 8.4+, featuring Symfony Clock integration, testable time manipulation, and native MongoDB support.

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

[](#installation)

```
composer require recruiterphp/clock
```

Requirements
------------

[](#requirements)

- PHP 8.4+
- MongoDB extension &gt;=1.15
- Symfony Clock ^7.3

Quick Start
-----------

[](#quick-start)

```
use Recruiter\Clock\ManualClock;
use Recruiter\Clock\SystemClock;
use Recruiter\DateTime\UTCDateTime;

// Production: Use system time
$clock = new SystemClock();
$now = $clock->now(); // Returns DateTimeImmutable

// Testing: Use fixed time (DateTime gets converted to DateTimeImmutable)
$clock = new ManualClock(new \DateTimeImmutable('2024-01-01 12:00:00'));
$fixedTime = $clock->now(); // Always returns 2024-01-01 12:00:00

// UTC DateTime with microsecond precision
$utcTime = UTCDateTime::now();
echo $utcTime->toIso8601WithMicroseconds(); // 2024-01-01T12:00:00.123456+0000

// MongoDB integration
$mongoClock = $clock->asMongoUTC();
$bsonDateTime = $mongoClock->now(); // Returns MongoDB\BSON\UTCDateTime
```

Core Interfaces
---------------

[](#core-interfaces)

### Clock

[](#clock)

Primary clock interface extending Symfony's ClockInterface:

```
use Symfony\Component\Clock\ClockInterface;

interface Clock extends ClockInterface
{
    // Methods from Symfony's ClockInterface:
    // - now(): \DateTimeImmutable
    // - sleep(float|int $seconds): void
    // - withTimeZone(\DateTimeZone|string $timezone): static

    // Additional methods for specialized clocks:
    public function asUTC(): UTCClock;
    public function asMongoUTC(): MongoUTCClock;
    public function asMicrotime(): MicrotimeClock;
    public function stopWatch(): StopWatch;
}
```

### UTCClock

[](#utcclock)

Specialized interface for custom UTC DateTime operations:

```
interface UTCClock
{
    public function now(): UTCDateTime;
}
```

### MongoUTCClock

[](#mongoutcclock)

Native MongoDB UTC DateTime interface:

```
interface MongoUTCClock
{
    public function now(): MongoDB\BSON\UTCDateTime;
}
```

Clock Implementations
---------------------

[](#clock-implementations)

### SystemClock

[](#systemclock)

Production clock using system time (wraps Symfony's NativeClock):

```
$clock = new SystemClock();
$now = $clock->now(); // Returns current DateTimeImmutable

// With timezone
$nyClock = new SystemClock('America/New_York');
```

### ManualClock

[](#manualclock)

Test clock with manual time control (wraps Symfony's MockClock):

```
// You can pass either DateTime or DateTimeImmutable - both work
$clock = new ManualClock(new \DateTimeImmutable('2024-01-01'));
// or use DateTime (gets converted internally to DateTimeImmutable)
$clock = new ManualClock(new \DateTime('2024-01-01'));
// or use the factory method
$clock = ManualClock::fromIso8601('2024-01-01T12:00:00Z');

// Advance time
$clock->advance(3600); // Advance 1 hour (seconds)
$clock->advance(new \DateInterval('P1D')); // Advance 1 day
```

### ProgressiveClock

[](#progressiveclock)

Auto-advancing clock that increments on each call:

```
$clock = new ProgressiveClock(
    new \DateTimeImmutable('2024-01-01'),
    new \DateInterval('PT1H') // Advance 1 hour each call
);

$time1 = $clock->now(); // 2024-01-01 00:00:00
$time2 = $clock->now(); // 2024-01-01 01:00:00
```

### SettableClock

[](#settableclock)

Switchable clock that can override any base clock:

```
$baseClock = new SystemClock();
$clock = new SettableClock($baseClock);

// Override with fixed time
$clock->nowIs(new \DateTimeImmutable('2024-01-01'));
$fixed = $clock->now(); // 2024-01-01

// Reset to base clock
$clock->reset();
$system = $clock->now(); // Current system time
```

### DelayedClock

[](#delayedclock)

Clock that returns time in the past:

```
$baseClock = new SystemClock();
$clock = new DelayedClock($baseClock, 3600); // 1 hour delay
$past = $clock->now(); // Returns time from 1 hour ago
```

UTCDateTime
-----------

[](#utcdatetime)

High-precision UTC datetime with MongoDB integration:

```
// Create from various sources
$utc = UTCDateTime::now();
$utc = UTCDateTime::fromString('2024-01-01T12:00:00Z');
$utc = UTCDateTime::fromTimestamp(1704110400);
$utc = UTCDateTime::fromMicrotime(microtime());

// Format output
echo $utc->toIso8601();                    // 2024-01-01T12:00:00+0000
echo $utc->toIso8601WithMicroseconds();    // 2024-01-01T12:00:00.123456+0000
echo $utc->toApiFormat();                  // 20240101120000

// MongoDB integration
$mongoDate = $utc->toMongoUTCDateTime();

// Date arithmetic
$later = $utc->addHours(2);
$earlier = $utc->subtractDays(1);
$tomorrow = $utc->add(new DateInterval('P1D'));

// Comparisons
$utc1->greaterThan($utc2);
$utc1->lessThanOrEqual($utc2);
```

Date Ranges
-----------

[](#date-ranges)

Work with date ranges and iterations:

```
use Recruiter\DateTime\UTCDateTimeRange;

$start = UTCDateTime::fromString('2024-01-01');
$end = UTCDateTime::fromString('2024-01-31');

$range = UTCDateTimeRange::fromTo($start, $end);

// Iterate by days
foreach ($range->dailyIterator() as $day) {
    echo $day->toIso8601Day(); // 2024-01-01, 2024-01-02, etc.
}

// Iterate by hours
foreach ($range->hourlyIterator() as $hour) {
    echo $hour->toIso8601(); // Every hour in the range
}
```

Testing
-------

[](#testing)

Perfect for testing time-dependent code:

```
use Recruiter\Clock\Clock;
use Recruiter\Clock\ManualClock;

class OrderService
{
    public function __construct(private Clock $clock) {}

    public function createOrder(): Order
    {
        return new Order($this->clock->now());
    }
}

// In tests
$testClock = new ManualClock(new \DateTimeImmutable('2024-01-01'));
$service = new OrderService($testClock);
$order = $service->createOrder();
// Order will always have 2024-01-01 timestamp

// Advance time to test time-based logic
$testClock->advance(3600); // 1 hour later
$laterOrder = $service->createOrder();
```

Development
-----------

[](#development)

### Docker Environment

[](#docker-environment)

```
# Build and start development environment
make build
make up

# Run tests
make test

# Open bash shell inside PHP container
make shell

# View logs
make logs

# Clean up
make clean
```

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance64

Regular maintenance activity

Popularity19

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 79.1% 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 ~232 days

Recently: every ~1 days

Total

11

Last Release

225d ago

Major Versions

1.0.0 → 2.0.02019-03-28

2.0.1 → 3.0.02019-06-05

3.0.2 → v4.0.02025-08-02

v4.2.0 → v5.0.02025-08-08

PHP version history (3 changes)1.0.0PHP &gt;=5.6

2.0.1PHP &gt;=7.1

v4.0.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/ed102e71a4ddc420660d84010ae0387b1c75340b77670e7e9a49d2964dd2ca80?d=identicon)[gabrielelana](/maintainers/gabrielelana)

![](https://www.gravatar.com/avatar/f3e93ddc6d8a23aa80fd9d3e1b62af4d04e035b698146659f4d606102fe4dee9?d=identicon)[silvadanilo](/maintainers/silvadanilo)

---

Top Contributors

[![dbellettini](https://avatars.githubusercontent.com/u/325358?v=4)](https://github.com/dbellettini "dbellettini (136 commits)")[![razielgn](https://avatars.githubusercontent.com/u/237493?v=4)](https://github.com/razielgn "razielgn (20 commits)")[![silvadanilo](https://avatars.githubusercontent.com/u/344657?v=4)](https://github.com/silvadanilo "silvadanilo (9 commits)")[![giorgiosironi](https://avatars.githubusercontent.com/u/160299?v=4)](https://github.com/giorgiosironi "giorgiosironi (4 commits)")[![gabrielelana](https://avatars.githubusercontent.com/u/50211?v=4)](https://github.com/gabrielelana "gabrielelana (3 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisRector

Code StylePHP CS Fixer

### Embed Badge

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

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

###  Alternatives

[symfony/security-bundle

Provides a tight integration of the Security component into the Symfony full-stack framework

2.5k168.9M1.6k](/packages/symfony-security-bundle)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.5M599](/packages/sylius-sylius)[lexik/jwt-authentication-bundle

This bundle provides JWT authentication for your Symfony REST API

2.6k57.5M185](/packages/lexik-jwt-authentication-bundle)[symfony/messenger

Helps applications send and receive messages to/from other applications or via message queues

1.1k116.9M796](/packages/symfony-messenger)[nesbot/carbon

An API extension for DateTime that supports 281 different languages.

164648.9M4.2k](/packages/nesbot-carbon)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)

PHPackages © 2026

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