README

Timezone-agnostic Date and Time value objects for PHP.

Why?

PHP's DateTime and DateTimeImmutable are powerful but carry timezone complexity that's unnecessary for many use cases:

• Birthdays - A birthday is January 15th, not "January 15th in UTC-5"
• Special Days - The Australia Day is on January 26th, The Independence Day is on July 4th - regardless of which time zone in Australia or the U.S. you are
• Business hours - Standard business hours across a global enterprise could be 9am to 5pm, regardless of where on Earth do you work for the business: you have to rock up at 9am for work, wherever you are.

When you want to store a date or time as a face value, without the time zone, you can find yourself fighting with the native \DateTimeInterface objects.

This package provides SimpleDateImmutable, SimpleDate, SimpleTimeImmutable, and SimpleTime classes that represent pure calendar dates and wall-clock times without timezone baggage.

Installation

composer require janklan/simple-date-time

Usage

Date

use JanKlan\SimpleDateTime\SimpleDateImmutable;

$birthday = new SimpleDateImmutable('1990-05-15');
$today = SimpleDateImmutable::today();
$christmas = SimpleDateImmutable::fromString('2025-12-25');

// Comparisons
$today->isBefore($christmas); // true
$today->isAfter($birthday);   // true
$today->isSame($birthday);    // false

// Arithmetic
$nextWeek = $today->modify('+1 week');

// Formatting (date characters only)
echo $birthday->format('l, F j, Y'); // "Tuesday, May 15, 1990"

Time

use JanKlan\SimpleDateTime\SimpleTimeImmutable;

$opening = new SimpleTimeImmutable('09:00:00');
$closing = SimpleTimeImmutable::create(17, 30, 0);
$now = SimpleTimeImmutable::now();
$midnight = SimpleTimeImmutable::midnight();
$noon = SimpleTimeImmutable::noon();

// Comparisons
$now->isBefore($closing);  // true (during business hours)
$now->isAfter($opening);   // true
$now->isSame($noon);       // false

// Arithmetic (wraps at midnight)
$lateNight = SimpleTimeImmutable::create(23, 0, 0);
$earlyMorning = $lateNight->modify('+2 hours'); // 01:00:00

// Formatting (time characters only)
echo $opening->format('g:i A'); // "9:00 AM"

Mutable Variants

Both SimpleDate and SimpleTime mutable variants are available, though immutable versions are recommended:

use JanKlan\SimpleDateTime\SimpleDate;
use JanKlan\SimpleDateTime\SimpleTime;

$date = new SimpleDate('2025-01-15');
$date->modify('+1 day'); // Modifies in place

$time = new SimpleTime('14:30:00');
$time->setTime(15, 0, 0); // Modifies in place

Blocked Operations

Operations that would leak time/timezone information throw exceptions:

// Date objects block time operations
$date->setTime(12, 0, 0);     // LogicException
$date->setTimezone($tz);      // LogicException
$date->format('H:i:s');       // InvalidArgumentException
$date->modify('+1 hour');     // LogicException

// Time objects block date operations
$time->setDate(2025, 1, 15);  // LogicException
$time->setTimezone($tz);      // LogicException
$time->format('Y-m-d');       // InvalidArgumentException
$time->modify('+1 day');      // LogicException

PHPStan Integration

The package includes a PHPStan rule that detects comparison operators used on date/time objects. To enable it, add to your phpstan.neon:

includes:
    - vendor/janklan/simple-date-time/phpstan-extension.neon

This catches errors like:

$date1 < $date2  // Error: Use isBefore() instead
$time1 == $time2 // Error: Use isSame() instead

Doctrine Integration

For database persistence, see janklan/simple-date-time-for-doctrine.

Contributing

PR are welcome. All you need to do to get started is to check out the repository, run composer install and you're done.

Several shorthand commands are configured in Composer: cs, phpstan, rector, test, and preflight. See composer.json to find out what they do.

Run composer preflight at least at the end of your work, before you create a pull request.

Code Coverage

Generate coverage reports in ./coverage:

composer test:cc

License

MIT