README

Time-related strategy interfaces for PHPNomad. A catalog of narrow capabilities that integration packages implement against any underlying time library — PSR-20, Carbon, Tokei, lcobucci/clock, symfony/clock, WordPress core, native PHP — so consumers can compose time-handling capabilities across libraries without touching call sites.

This package ships interfaces only. Pair it with one or more integration packages — for example phpnomad/wordpress-integration, which binds WordPress's current_datetime(), wp_timezone(), wp_date(), and human_time_diff() to the appropriate interfaces.

Requirements

PHP 8.2 or newer.

Installation

composer require phpnomad/chrono

You will also need at least one concrete ClockStrategy binding. On WordPress, install phpnomad/wordpress-integration and the wiring is automatic. Elsewhere, bind any PSR-20 ClockInterface implementation (e.g. lcobucci/clock or symfony/clock) to ClockStrategy in your composition root.

Usage

Inject the capabilities you need. A consumer that does not care about formatting or arithmetic depends on ClockStrategy alone:

use DateTimeImmutable;
use PHPNomad\Chrono\Interfaces\CanCheckIfPast;
use PHPNomad\Chrono\Interfaces\ClockStrategy;

final class TokenService
{
    public function __construct(
        private ClockStrategy $clock,
        private CanCheckIfPast $past,
    ) {}

    public function isExpired(DateTimeImmutable $expiresAt): bool
    {
        return $this->past->isPast($expiresAt);
    }

    public function issueExpiringIn(string $relative): DateTimeImmutable
    {
        return $this->clock->now()->modify($relative);
    }
}

In tests, bind a frozen ClockStrategy and a stub CanCheckIfPast:

$clock = new Lcobucci\Clock\FrozenClock(new DateTimeImmutable('2026-05-27T12:00:00Z'));
$past  = new class ($clock) implements CanCheckIfPast {
    public function __construct(private ClockStrategy $clock) {}
    public function isPast(DateTimeImmutable $i): bool { return $i < $this->clock->now(); }
};
$service = new TokenService($clock, $past);

$this->assertFalse($service->isExpired(new DateTimeImmutable('2026-05-27T13:00:00Z')));
$this->assertTrue($service->isExpired(new DateTimeImmutable('2026-05-27T11:00:00Z')));

Catalog

Each interface is narrow — one or a few related methods — so integrators can implement whatever subset their underlying library naturally covers. A single concrete class can implement many interfaces.

Clock and provider state

Interface	Method	Notes
`ClockStrategy`	`now(): DateTimeImmutable`	Extends `Psr\Clock\ClockInterface`
`HasTimezone`	`getTimezone(): DateTimeZone`	Platform's configured timezone
`HasLocale`	`getLocale(): string`	Platform's configured locale (BCP 47 / POSIX style)

Predicates on a single instant

Interface	Method
`CanCheckIfPast`	`isPast(DateTimeImmutable $instant): bool`
`CanCheckIfFuture`	`isFuture(DateTimeImmutable $instant): bool`
`CanCheckIfWeekend`	`isWeekend(DateTimeImmutable $instant): bool`
`CanCheckIfWeekday`	`isWeekday(DateTimeImmutable $instant): bool`

Predicates on two instants

Interface	Method
`CanCheckSameDay`	`isSameDay(DateTimeImmutable $a, DateTimeImmutable $b): bool`
`CanCheckSameMonth`	`isSameMonth(DateTimeImmutable $a, DateTimeImmutable $b): bool`
`CanCheckSameYear`	`isSameYear(DateTimeImmutable $a, DateTimeImmutable $b): bool`
`CanCheckBetween`	`isBetween(DateTimeImmutable $i, DateTimeImmutable $start, DateTimeImmutable $end): bool`

Arithmetic

Interface	Method
`CanApplyModifier`	`apply(DateTimeImmutable $instant, string $modifier): DateTimeImmutable`
`CanAddInterval`	`add(DateTimeImmutable $instant, DateInterval $interval): DateTimeImmutable`
`CanSubtractInterval`	`subtract(DateTimeImmutable $instant, DateInterval $interval): DateTimeImmutable`

Calendar boundaries

Interface	Method
`CanGetStartOfDay`	`startOfDay(DateTimeImmutable $instant): DateTimeImmutable`
`CanGetEndOfDay`	`endOfDay(DateTimeImmutable $instant): DateTimeImmutable`
`CanGetStartOfMonth`	`startOfMonth(DateTimeImmutable $instant): DateTimeImmutable`
`CanGetEndOfMonth`	`endOfMonth(DateTimeImmutable $instant): DateTimeImmutable`
`CanGetStartOfYear`	`startOfYear(DateTimeImmutable $instant): DateTimeImmutable`
`CanGetEndOfYear`	`endOfYear(DateTimeImmutable $instant): DateTimeImmutable`

Difference and duration

Interface	Method
`CanGetDifference`	`diff(DateTimeImmutable $a, DateTimeImmutable $b): DateInterval`
`CanGetDifferenceInDays`	`diffInDays(DateTimeImmutable $a, DateTimeImmutable $b): int`
`CanGetDifferenceInHours`	`diffInHours(DateTimeImmutable $a, DateTimeImmutable $b): int`
`CanGetDifferenceInMinutes`	`diffInMinutes(DateTimeImmutable $a, DateTimeImmutable $b): int`
`CanGetDifferenceInSeconds`	`diffInSeconds(DateTimeImmutable $a, DateTimeImmutable $b): int`

Parsing

Interface	Method
`CanParseDate`	`parse(string $expression): DateTimeImmutable`
`CanParseDateWithFormat`	`parseFormat(string $expression, string $format): DateTimeImmutable`

Formatting

Interface	Method
`CanFormatDate`	`format(DateTimeImmutable $instant, string $format): string`
`CanFormatLocalizedDate`	`formatLocalized(DateTimeImmutable $instant, string $format): string`
`CanFormatRelativeTime`	`relative(DateTimeImmutable $instant): string` ("3 hours ago")

Model contracts

These two are model-side contracts for persisted records — every PHPNomad model that participates in audit trails implements them.

Interface	Method
`HasCreatedDate`	`getCreatedDate(): DateTimeImmutable`
`HasModifiedDate`	`getModifiedDate(): DateTimeImmutable`

How integrations compose the catalog

An integration package ships one or more concrete classes that implement the cluster of interfaces its underlying library can naturally fulfill. phpnomad/wordpress-integration ships a class implementing the WordPress-specific subset:

class WordPressClockStrategy implements
    ClockStrategy,
    HasTimezone,
    CanFormatLocalizedDate,
    CanFormatRelativeTime
{
    public function now(): DateTimeImmutable { /* current_datetime() */ }
    public function getTimezone(): DateTimeZone { /* wp_timezone() */ }
    public function formatLocalized(DateTimeImmutable $i, string $f): string { /* wp_date() */ }
    public function relative(DateTimeImmutable $i): string { /* human_time_diff() */ }
}

A hypothetical phpnomad/carbon-integration would ship a class implementing the much broader Carbon-backed cluster (predicates, arithmetic, boundaries, diff, parsing, formatting). A consumer that needs WordPress's timezone alongside Carbon's diff math binds each interface to the appropriate concrete.

Why a catalog of narrow interfaces

A single fat TimeStrategy interface would force every integrator to implement methods their underlying library does not naturally support. A catalog of narrow interfaces lets integrators declare exactly what their library covers, and lets consumers depend only on the capabilities they use. Integrations declare PHPNomad support by implementing the relevant interfaces; consumers compose multiple integrations across libraries as needed.

License

MIT

phpnomad / chrono

Maintainers

Package info

Statistics

Security