PHPackages                             janklan/simple-date-time - 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. [Utility & Helpers](/categories/utility)
4. /
5. janklan/simple-date-time

ActiveLibrary[Utility & Helpers](/categories/utility)

janklan/simple-date-time
========================

Timezone-agnostic Date and Time value objects for PHP

00[1 PRs](https://github.com/janklan/simple-date-time/pulls)PHPCI passing

Since Dec 8Pushed 4mo agoCompare

[ Source](https://github.com/janklan/simple-date-time)[ Packagist](https://packagist.org/packages/janklan/simple-date-time)[ RSS](/packages/janklan-simple-date-time/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

Simple Date Time
================

[](#simple-date-time)

[![Packagist Version](https://camo.githubusercontent.com/32cd82547e3e7f99fdaab918e196a8179cadad86b1f711a5ce508f56938f2a90/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a616e6b6c616e2f73696d706c652d646174652d74696d65)](https://camo.githubusercontent.com/32cd82547e3e7f99fdaab918e196a8179cadad86b1f711a5ce508f56938f2a90/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a616e6b6c616e2f73696d706c652d646174652d74696d65)[![CI](https://github.com/janklan/simple-date-time/actions/workflows/ci.yml/badge.svg)](https://github.com/janklan/simple-date-time/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/ea164eea37e388767e934dfe8ac3fd0165c8474bc5c51aa14804f55c5c501405/68747470733a2f2f636f6465636f762e696f2f67682f6a616e6b6c616e2f73696d706c652d646174652d74696d652f67726170682f62616467652e737667)](https://codecov.io/gh/janklan/simple-date-time)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

Timezone-agnostic Date and Time value objects for PHP.

Why?
----

[](#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
------------

[](#installation)

```
composer require janklan/simple-date-time
```

Usage
-----

[](#usage)

### Date

[](#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

[](#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

[](#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

[](#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
-------------------

[](#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
--------------------

[](#doctrine-integration)

For database persistence, see [janklan/simple-date-time-for-doctrine](https://github.com/janklan/simple-date-time-for-doctrine).

Contributing
------------

[](#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

[](#code-coverage)

Generate coverage reports in `./coverage`:

```
composer test:cc
```

License
-------

[](#license)

MIT

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance50

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

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

---

Top Contributors

[![janklan](https://avatars.githubusercontent.com/u/5463371?v=4)](https://github.com/janklan "janklan (1 commits)")

### Embed Badge

![Health badge](/badges/janklan-simple-date-time/health.svg)

```
[![Health](https://phpackages.com/badges/janklan-simple-date-time/health.svg)](https://phpackages.com/packages/janklan-simple-date-time)
```

###  Alternatives

[tinect/redirects

Redirect plugin for Shopware 6

2040.6k](/packages/tinect-redirects)[defstudio/filament-column-length-limiter

Limit Filament columns length showing a tooltip when text exceeds

126.2k](/packages/defstudio-filament-column-length-limiter)

PHPackages © 2026

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