README

A simple PSR-20 Clock implementation for accessing and mocking the current time.

Getting Started
Clocks
- UTCClock - Provides UTC times. (Should be your primary clock used)
- AlternateTimeZoneClock - Provides times in a specified timezone based on time from another clock.
- FrozenClock - Provides only the specified time. (Great for mocking and testing)
- SystemClock - Provides times in the specified timezone. (Use at your own will)
ClockInterface

Getting Started

composer require ordinary/clock

Usage

<?php

use Ordinary\Clock\ClockInterface;
use Ordinary\Clock\UTCClock;

class MyTimeAwareAction
{
    public function __construct(protected ClockInterface $clock)
    {
    }
    
    public function announceTime(): void
    {
        echo 'Time is now ' . $this->clock->now()->format('c') . PHP_EOL;
    }
}

$action = new MyTimeAwareAction(new UTCClock());
$action->announceTime();

Clocks

UTCClock

A clock that always returns date objects in UTC.

This should be the primary clock used when managing time.

$clock = new UTCClock();

AlternateTimeZoneClock

A clock that wraps another clock for use in different timezones.

Generally this clock should wrap a UTC clock when timezone specific operations are needed.

$clock = new AlternateTimeZoneClock($primaryClock = new UTCClock(), new DateTimeZone('America/Chicago'))

FrozenClock

A clock that only returns the specific time given on construct.

Generally used for mocking time.

SystemClock

A clock that can be constructing with a valid timezone.

$clock = new \Ordinary\Clock\SystemClock(new DateTimeZone('America/Chicago'));

ClockInterface Methods

`ClockInterface::now()`

Get a DateTimeImmutable instance representing the current time.

`ClockInterface::isBefore($dateTime)`

Check to see if the given time is in the future.
Exclusive of given time

`ClockInterface::isAfter($dateTime)`

Check to see if a given time is in the past.
Exclusive of the given time

`ClockInterface::isAtEarliest($dateTime)`

Check to see if at the earliest, it is the given time.
Inclusive version of isAfter()

`ClockInterface::isAtLatest($dateTime)`

Check to see if at the latest, it is the given time.
Inclusive version of isBefore()

`ClockInterface::isBetween($startDate, $endDate)`

Check to see if the current time falls in between the provided times.
Exclusive of provided times

`ClockInterface::isBetweenInclusive($startDate, $endDate)`

Check to see if the current time falls in between the provided times.
Inclusive of provided times

`ClockInterface::isBetweenInclusiveStart($startDate, $endDate)`

Check to see if the current time falls in between the provided times.
Inclusive ONLY of start time
For situations similar to the given range being 1:00, 2:00 but needing to verify the time is anything from 1:00 and 1:59.

ordinary / clock

Maintainers

Details