PHPackages                             delight-im/temporal - 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. delight-im/temporal

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

delight-im/temporal
===================

Immutable date and time for PHP with a convenient interface

v1.2.0(8y ago)13154[2 issues](https://github.com/delight-im/PHP-Temporal/issues)MITPHPPHP >=5.6.0

Since Apr 3Pushed 8y ago1 watchersCompare

[ Source](https://github.com/delight-im/PHP-Temporal)[ Packagist](https://packagist.org/packages/delight-im/temporal)[ Docs](https://github.com/delight-im/PHP-Temporal)[ RSS](/packages/delight-im-temporal/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (4)Used By (0)

PHP-Temporal
============

[](#php-temporal)

Immutable date and time for PHP with a convenient interface

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

[](#requirements)

- PHP 5.6.0+

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

[](#installation)

1. Include the library via Composer [\[?\]](https://github.com/delight-im/Knowledge/blob/master/Composer%20(PHP).md):

    ```
    $ composer require delight-im/temporal

    ```
2. Include the Composer autoloader:

    ```
    require __DIR__ . '/vendor/autoload.php';
    ```
3. Make sure to set your default time zone in PHP, e.g.:

    ```
    \date_default_timezone_set('America/Los_Angeles');
    ```

Usage
-----

[](#usage)

- [Creating instances and parsing dates and time](#creating-instances-and-parsing-dates-and-time)
- [Adding and subtracting date and time](#adding-and-subtracting-date-and-time)
- [Fetching individual components or units of date and time](#fetching-individual-components-or-units-of-date-and-time)
- [Modifying individual components or units of date and time](#modifying-individual-components-or-units-of-date-and-time)
- [Skipping to boundaries of date and time units](#skipping-to-boundaries-of-date-and-time-units)
- [Formatting and outputting date and time](#formatting-and-outputting-date-and-time)
- [Fetching decades, centuries and millennia from dates](#fetching-decades-centuries-and-millennia-from-dates)
- [Checking for daylight saving time (DST)](#checking-for-daylight-saving-time-dst)
- [Checking for leap years](#checking-for-leap-years)
- [Checking for special dates](#checking-for-special-dates)
- [Calculating differences between two instances of date and time](#calculating-differences-between-two-instances-of-date-and-time)
- [Reading and writing durations of date and time](#reading-and-writing-durations-of-date-and-time)
- [Comparing instances of date and time with each other](#comparing-instances-of-date-and-time-with-each-other)
    - [Equality](#equality)
    - [Less than](#less-than)
    - [Greater than](#greater-than)
    - [Less than or equal to](#less-than-or-equal-to)
    - [Greater than or equal to](#greater-than-or-equal-to)
- [Checking whether dates and times are in the past or future](#checking-whether-dates-and-times-are-in-the-past-or-future)
- [Changing and converting timezones](#changing-and-converting-timezones)

### Creating instances and parsing dates and time

[](#creating-instances-and-parsing-dates-and-time)

```
$dateTime = \Delight\Temporal\Temporal::now();
// or
$dateTime = \Delight\Temporal\Temporal::now('Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromUnixSeconds(-14182916);
// or
$dateTime = \Delight\Temporal\Temporal::fromUnixSeconds(-14182916, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromUnixMillis(-14182916000);
// or
$dateTime = \Delight\Temporal\Temporal::fromUnixMillis(-14182916000, 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeExtended('1969-07-20T20:18:04+00:00');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeExtended('1969-07-20T20:18:04Z', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeBasic('19690720T201804Z');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeBasic('19690720T201804+0000', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601DateExtended('1969-07-20');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateExtended('1969-07-20', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateBasic('19690720');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateBasic('19690720', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeExtended('20:18:04Z');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeExtended('20:18:04+00:00', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeBasic('201804+0000');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeBasic('201804Z', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromDateTime(1969, 7, 20, 20, 18, 4);
// or
$dateTime = \Delight\Temporal\Temporal::fromDateTime(1969, 7, 20, 20, 18, 4, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromDate(1969, 7, 20);
// or
$dateTime = \Delight\Temporal\Temporal::fromDate(1969, 7, 20, 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromTime(20, 18, 4);
// or
$dateTime = \Delight\Temporal\Temporal::fromTime(20, 18, 4, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromFormat('20.07.1969', 'd.m.Y');
// or
$dateTime = \Delight\Temporal\Temporal::fromFormat('20.07.1969', 'd.m.Y', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromDateTimeInterface(new \DateTime());
// or
$dateTime = \Delight\Temporal\Temporal::fromDateTimeInterface(new \DateTimeImmutable());

// or

$dateTime = \Delight\Temporal\Temporal::yesterday();
// or
$dateTime = \Delight\Temporal\Temporal::yesterday('America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::tomorrow();
// or
$dateTime = \Delight\Temporal\Temporal::tomorrow('America/Los_Angeles');
```

### Adding and subtracting date and time

[](#adding-and-subtracting-date-and-time)

```
$dateTime = $dateTime->plusYears(7);
// or
$dateTime = $dateTime->minusYears(4);

// or

$dateTime = $dateTime->plusMonths(30);
// or
$dateTime = $dateTime->minusMonths(8);

// or

$dateTime = $dateTime->plusWeeks(6);
// or
$dateTime = $dateTime->minusWeeks(2);

// or

$dateTime = $dateTime->plusDays(28);
// or
$dateTime = $dateTime->minusDays(100);

// or

$dateTime = $dateTime->plusHours(36);
// or
$dateTime = $dateTime->minusHours(19);

// or

$dateTime = $dateTime->plusMinutes(90);
// or
$dateTime = $dateTime->minusMinutes(47);

// or

$dateTime = $dateTime->plusSeconds(30);
// or
$dateTime = $dateTime->minusSeconds(125);

// or

$dateTime = $dateTime->plusDuration('P3Y6M4DT12H30M5S');
// or
$dateTime = $dateTime->minusDuration('P3Y6M4DT12H30M5S');

// or

$dateTime = $dateTime->plusMonths(6)->plusWeeks(2)->minusDays(3);
```

### Fetching individual components or units of date and time

[](#fetching-individual-components-or-units-of-date-and-time)

```
$dateTime->getYear();
// or
$dateTime->getMonth();
// or
$dateTime->getDay();
// or
$dateTime->getHour();
// or
$dateTime->getMinute();
// or
$dateTime->getSecond();

// or

$dateTime->getWeekday();

// or

$dateTime->isMonday();
// or
$dateTime->isTuesday();
// or
$dateTime->isWednesday();
// or
$dateTime->isThursday();
// or
$dateTime->isFriday();
// or
$dateTime->isSaturday();
// or
$dateTime->isSunday();

// or

$dateTime->getWeekOfYear();
// or
$dateTime->getWeekYear();
// or
$dateTime->getDayOfYear();
```

### Modifying individual components or units of date and time

[](#modifying-individual-components-or-units-of-date-and-time)

```
$dateTime = $dateTime->withYear(1969);
// or
$dateTime = $dateTime->withMonth(7);
// or
$dateTime = $dateTime->withDay(20);
// or
$dateTime = $dateTime->withHour(20);
// or
$dateTime = $dateTime->withMinute(18);
// or
$dateTime = $dateTime->withSecond(4);

// or

$dateTime = $dateTime->withDate(1969, 7, 20);
// or
$dateTime = $dateTime->withTime(20, 18, 4);

// or

$dateTime = $dateTime->withDate(1969, 7, 20)->withMinute(0)->withSecond(0);
```

### Skipping to boundaries of date and time units

[](#skipping-to-boundaries-of-date-and-time-units)

```
$dateTime = $dateTime->startOfMinute();
// or
$dateTime = $dateTime->endOfMinute();

// or

$dateTime = $dateTime->startOfHour();
// or
$dateTime = $dateTime->endOfHour();

// or

$dateTime = $dateTime->startOfDay();
// or
$dateTime = $dateTime->endOfDay();

// or

$dateTime = $dateTime->startOfWeek();
// or
$dateTime = $dateTime->endOfWeek();

// or

$dateTime = $dateTime->startOfMonth();
// or
$dateTime = $dateTime->endOfMonth();

// or

$dateTime = $dateTime->startOfYear();
// or
$dateTime = $dateTime->endOfYear();

// or

$dateTime = $dateTime->startOfDecade();
// or
$dateTime = $dateTime->endOfDecade();

// or

$dateTime = $dateTime->startOfCentury();
// or
$dateTime = $dateTime->endOfCentury();

// or

$dateTime = $dateTime->startOfMillennium();
// or
$dateTime = $dateTime->endOfMillennium();

// or

$dateTime = $dateTime->startOfMonth()->endOfWeek()->startOfDay();
```

### Formatting and outputting date and time

[](#formatting-and-outputting-date-and-time)

```
$dateTime->toIso8601DateTimeExtended();
// or
$dateTime->toIso8601DateTimeBasic();

// or

$dateTime->toIso8601DateExtended();
// or
$dateTime->toIso8601DateBasic();

// or

$dateTime->toIso8601TimeExtended();
// or
$dateTime->toIso8601TimeBasic();

// or

$dateTime->toUnixSeconds();
// or
$dateTime->toUnixMillis();

// or

$dateTime->toFormat('d.m.Y');
// or
$dateTime->toFormat('l jS \of F Y h:i:s A');

// or

$dateTime->toDateTime();
// or
$dateTime->toDateTimeImmutable();
```

### Fetching decades, centuries and millennia from dates

[](#fetching-decades-centuries-and-millennia-from-dates)

```
$dateTime->getDecadeOrdinal();
// or
$dateTime->getDecadeNominal();
// or
$dateTime->getYearInDecade();

// or

$dateTime->getCenturyOrdinal();
// or
$dateTime->getCenturyNominal();
// or
$dateTime->getYearInCentury();

// or

$dateTime->getMillenniumOrdinal();
// or
$dateTime->getMillenniumNominal();
// or
$dateTime->getYearInMillennium();
```

### Checking for daylight saving time (DST)

[](#checking-for-daylight-saving-time-dst)

```
$dateTime->isDst();
```

### Checking for leap years

[](#checking-for-leap-years)

```
$dateTime->isLeapYear();
```

### Checking for special dates

[](#checking-for-special-dates)

```
$dateTime->isToday();
// or
$dateTime->isYesterday();
// or
$dateTime->isTomorrow();

// or

$dateTime->isAnniversary();

// or

$dateTime->isThisWeek();
// or
$dateTime->isLastWeek();
// or
$dateTime->isNextWeek();

// or

$dateTime->isThisMonth();
// or
$dateTime->isLastMonth();
// or
$dateTime->isNextMonth();

// or

$dateTime->isThisYear();
// or
$dateTime->isLastYear();
// or
$dateTime->isNextYear();

// or

$dateTime->isThisDecade();
// or
$dateTime->isLastDecade();
// or
$dateTime->isNextDecade();

// or

$dateTime->isThisCentury();
// or
$dateTime->isLastCentury();
// or
$dateTime->isNextCentury();

// or

$dateTime->isThisMillennium();
// or
$dateTime->isLastMillennium();
// or
$dateTime->isNextMillennium();
```

### Calculating differences between two instances of date and time

[](#calculating-differences-between-two-instances-of-date-and-time)

```
$dateTime->calculateMillisUntil($otherDateTime);
// or
$dateTime->calculateSecondsUntil($otherDateTime);
// or
$dateTime->calculateMinutesUntil($otherDateTime);

// or

\Delight\Temporal\Duration $duration = $dateTime->calculateDurationUntil($otherDateTime);
```

### Reading and writing durations of date and time

[](#reading-and-writing-durations-of-date-and-time)

```
$duration->getYears();
// or
$duration->getMonths();
// or
$duration->getWeeks();
// or
$duration->getDays();

// or

$duration->getHours();
// or
$duration->getMinutes();
// or
$duration->getSeconds();

// or

$duration->isPositive();
// or
$duration->isNegative();
// or
$duration->getSign();

// or

$duration->toIso8601();

// or

$duration->toAverageYears();
// or
$duration->toAverageMonths();
// or
$duration->toAverageWeeks();
// or
$duration->toAverageDays();
// or
$duration->toAverageHours();
// or
$duration->toAverageMinutes();
// or
$duration->toAverageSeconds();

// or

$duration = \Delight\Temporal\Duration::fromDateTime(2, 7, 15, 20, 45, 0);
// or
$duration = \Delight\Temporal\Duration::fromDateTime(4, 0, 7);
// or
$duration = \Delight\Temporal\Duration::fromDateTime(3, 5, 26, 0, 0, 0, -1);

// or

$duration = \Delight\Temporal\Duration::fromWeeks(42);
// or
$duration = \Delight\Temporal\Duration::fromWeeks(8, -1);

// or

$duration = \Delight\Temporal\Duration::fromIso8601('P1M');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P1Y14D');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P1MT12H');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P3Y6M4DT12H30M5S');

// or

$duration = $duration->plus($otherDuration);
// or
$duration = $duration->multipliedBy(4);
// or
$duration = $duration->invert();

// or

$duration = $duration->plus($otherDuration->invert())->multipliedBy(2);
```

### Comparing instances of date and time with each other

[](#comparing-instances-of-date-and-time-with-each-other)

#### Equality

[](#equality)

```
$dateTime->isSame($otherDateTime);
// or
$dateTime->isMinuteSame($otherDateTime);
// or
$dateTime->isHourSame($otherDateTime);
// or
$dateTime->isDaySame($otherDateTime);
// or
$dateTime->isMonthSame($otherDateTime);
// or
$dateTime->isYearSame($otherDateTime);
// or
$dateTime->isDecadeSame($otherDateTime);
// or
$dateTime->isCenturySame($otherDateTime);
// or
$dateTime->isMillenniumSame($otherDateTime);
```

#### Less than

[](#less-than)

```
$dateTime->isBefore($otherDateTime);
// or
$dateTime->isMinuteBefore($otherDateTime);
// or
$dateTime->isHourBefore($otherDateTime);
// or
$dateTime->isDayBefore($otherDateTime);
// or
$dateTime->isMonthBefore($otherDateTime);
// or
$dateTime->isYearBefore($otherDateTime);
// or
$dateTime->isDecadeBefore($otherDateTime);
// or
$dateTime->isCenturyBefore($otherDateTime);
// or
$dateTime->isMillenniumBefore($otherDateTime);
```

#### Greater than

[](#greater-than)

```
$dateTime->isAfter($otherDateTime);
// or
$dateTime->isMinuteAfter($otherDateTime);
// or
$dateTime->isHourAfter($otherDateTime);
// or
$dateTime->isDayAfter($otherDateTime);
// or
$dateTime->isMonthAfter($otherDateTime);
// or
$dateTime->isYearAfter($otherDateTime);
// or
$dateTime->isDecadeAfter($otherDateTime);
// or
$dateTime->isCenturyAfter($otherDateTime);
// or
$dateTime->isMillenniumAfter($otherDateTime);
```

#### Less than or equal to

[](#less-than-or-equal-to)

```
$dateTime->isBeforeOrSame($otherDateTime);
// or
$dateTime->isMinuteBeforeOrSame($otherDateTime);
// or
$dateTime->isHourBeforeOrSame($otherDateTime);
// or
$dateTime->isDayBeforeOrSame($otherDateTime);
// or
$dateTime->isMonthBeforeOrSame($otherDateTime);
// or
$dateTime->isYearBeforeOrSame($otherDateTime);
// or
$dateTime->isDecadeBeforeOrSame($otherDateTime);
// or
$dateTime->isCenturyBeforeOrSame($otherDateTime);
// or
$dateTime->isMillenniumBeforeOrSame($otherDateTime);
```

#### Greater than or equal to

[](#greater-than-or-equal-to)

```
$dateTime->isAfterOrSame($otherDateTime);
// or
$dateTime->isMinuteAfterOrSame($otherDateTime);
// or
$dateTime->isHourAfterOrSame($otherDateTime);
// or
$dateTime->isDayAfterOrSame($otherDateTime);
// or
$dateTime->isMonthAfterOrSame($otherDateTime);
// or
$dateTime->isYearAfterOrSame($otherDateTime);
// or
$dateTime->isDecadeAfterOrSame($otherDateTime);
// or
$dateTime->isCenturyAfterOrSame($otherDateTime);
// or
$dateTime->isMillenniumAfterOrSame($otherDateTime);
```

### Checking whether dates and times are in the past or future

[](#checking-whether-dates-and-times-are-in-the-past-or-future)

```
$dateTime->isPast();
// or
$dateTime->isPastMinute();
// or
$dateTime->isPastHour();
// or
$dateTime->isPastDay();
// or
$dateTime->isPastMonth();
// or
$dateTime->isPastYear();
// or
$dateTime->isPastDecade();
// or
$dateTime->isPastCentury();
// or
$dateTime->isPastMillennium();

// or

$dateTime->isFuture();
// or
$dateTime->isFutureMinute();
// or
$dateTime->isFutureHour();
// or
$dateTime->isFutureDay();
// or
$dateTime->isFutureMonth();
// or
$dateTime->isFutureYear();
// or
$dateTime->isFutureDecade();
// or
$dateTime->isFutureCentury();
// or
$dateTime->isFutureMillennium();
```

### Changing and converting timezones

[](#changing-and-converting-timezones)

```
$dateTime = $dateTime->withTimeZone('UTC');
// or
$dateTime = $dateTime->withTimeZone('America/Los_Angeles');
// or
$dateTime = $dateTime->withTimeZone('Asia/Tokyo');

// or

$dateTime = $dateTime->withDefaultTimeZone();
```

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

[](#contributing)

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.

License
-------

[](#license)

This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT).

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance17

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity60

Established project with proven stability

 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.

###  Release Activity

Cadence

Every ~189 days

Total

3

Last Release

2996d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6597567?v=4)[delight.im](/maintainers/delight-im)[@delight-im](https://github.com/delight-im)

---

Top Contributors

[![ocram](https://avatars.githubusercontent.com/u/1681478?v=4)](https://github.com/ocram "ocram (9 commits)")

---

Tags

manipulationdatetimeformattimedateparseparsingformattingimmutablemanipulatedate-time

### Embed Badge

![Health badge](/badges/delight-im-temporal/health.svg)

```
[![Health](https://phpackages.com/badges/delight-im-temporal/health.svg)](https://phpackages.com/packages/delight-im-temporal)
```

###  Alternatives

[aeon-php/calendar

PHP type safe, immutable calendar library

20410.2M16](/packages/aeon-php-calendar)[fightbulc/moment

Parse, validate, manipulate, and display dates in PHP w/ i18n support. Inspired by moment.js

9683.3M12](/packages/fightbulc-moment)[league/period

Time range API for PHP

7335.7M22](/packages/league-period)[lawondyss/moment-php

MomentPHP is library for parsing, manipulating and formatting dates.

1419.0k](/packages/lawondyss-moment-php)[brick/date-time

Date and time library

3623.6M94](/packages/brick-date-time)[tplaner/when

Date/Calendar recursion library.

5261.1M7](/packages/tplaner-when)

PHPackages © 2026

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