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

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

php-temporal/php-temporal
=========================

A port of the JavaScript Temporal API for PHP

10[10 PRs](https://github.com/thomasschiet/php-temporal/pulls)PHPCI passing

Since Feb 20Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/thomasschiet/php-temporal)[ Packagist](https://packagist.org/packages/php-temporal/php-temporal)[ RSS](/packages/php-temporal-php-temporal/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (14)Used By (0)

PHP Temporal
============

[](#php-temporal)

A faithful port of the [TC39 Temporal API](https://tc39.es/proposal-temporal/docs/) to PHP.

PHP Temporal provides a complete, modern date/time library with nanosecond precision, DST-aware arithmetic, and multi-calendar support — all without depending on `\DateTime` or any PHP extensions.

Features
--------

[](#features)

- **All 11 Temporal types** — `PlainDate`, `PlainTime`, `PlainDateTime`, `Duration`, `Instant`, `ZonedDateTime`, `TimeZone`, `Calendar`, `PlainYearMonth`, `PlainMonthDay`, `Now`
- **Fully immutable** — every operation returns a new instance
- **Nanosecond precision** — `Instant` and `ZonedDateTime` track time to the nanosecond
- **DST-aware** — `ZonedDateTime` correctly handles daylight saving transitions and ambiguous/skipped times
- **ISO 8601 parsing** — extended years, calendar annotations, UTC offset suffixes
- **Multi-calendar support** — ISO 8601, Gregorian (with eras), and Buddhist calendars, extensible via `CalendarProtocol`
- **Typed exceptions** — a 9-class exception hierarchy under `Temporal\Exception`
- **Zero runtime dependencies** — pure PHP, no extensions required
- **5,400+ tests** — including 4,200+ from the TC39 test262 reference suite

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

[](#requirements)

- PHP 8.4 or 8.5

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

[](#installation)

```
composer require php-temporal/php-temporal
```

Quick Start
-----------

[](#quick-start)

### Dates

[](#dates)

```
use Temporal\PlainDate;

$date = PlainDate::from('2025-03-14');

$later = $date->add(['months' => 1, 'days' => 5]);
echo $later; // 2025-04-19

$duration = $date->until(PlainDate::from('2025-12-31'));
echo $duration->days; // 292
```

### Times

[](#times)

```
use Temporal\PlainTime;

$time = PlainTime::from('09:30:00');

$later = $time->add(['minutes' => 90]);
echo $later; // 11:00:00

$rounded = $time->round(['smallestUnit' => 'minute', 'roundingIncrement' => 15]);
echo $rounded; // 09:30:00
```

### Durations

[](#durations)

```
use Temporal\Duration;

$d = Duration::from('P1Y2M3DT4H5M6S');
echo $d->years;  // 1
echo $d->months; // 2

$balanced = Duration::from(['hours' => 25])->balance('days');
echo $balanced; // P1DT1H
```

### Instants and Time Zones

[](#instants-and-time-zones)

```
use Temporal\Instant;
use Temporal\ZonedDateTime;

$instant = Instant::fromEpochMilliseconds(1741939200000);
$zdt = $instant->toZonedDateTimeISO('Europe/Amsterdam');
echo $zdt->toPlainDate(); // 2025-03-14

$zdt = ZonedDateTime::from('2025-03-14T09:30:00[Europe/Amsterdam]');
echo $zdt->offset; // +01:00

// DST-aware arithmetic
$zdt2 = $zdt->add(['months' => 1]);
```

### Current Time

[](#current-time)

```
use Temporal\Now;

$instant = Now::instant();
$date    = Now::plainDateISO('Europe/Amsterdam');
$time    = Now::plainTimeISO('America/New_York');
$tz      = Now::timeZoneId();
```

API Overview
------------

[](#api-overview)

TypeDescription`PlainDate`Calendar date (year, month, day) without time or time zone`PlainTime`Wall-clock time without date or time zone`PlainDateTime`Date and time without time zone`Duration`Length of time (years through nanoseconds)`Instant`Exact moment on the UTC timeline (nanosecond precision)`ZonedDateTime`Date/time in a specific time zone (DST-aware)`TimeZone`IANA time zone or fixed UTC offset`Calendar`Calendar system (ISO 8601, Gregorian, Buddhist)`PlainYearMonth`Year and month without a day`PlainMonthDay`Month and day without a year`Now`Static helpers for the current date, time, and instantDevelopment
-----------

[](#development)

```
# Install dependencies
composer install

# Run core tests
./vendor/bin/phpunit --testsuite Temporal

# Run TC39 test262 reference tests
./vendor/bin/phpunit --testsuite test262

# Run all tests
./vendor/bin/phpunit

# Format, lint, and analyze
./vendor/bin/mago fmt
./vendor/bin/mago lint
./vendor/bin/mago analyze
```

License
-------

[](#license)

MIT

###  Health Score

23

—

LowBetter than 26% of packages

Maintenance59

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity22

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/27ff322ee2ea15e80b13a88434479f0dcb92185b65f9d5e3c25339d9f8470092?d=identicon)[thomasschiet](/maintainers/thomasschiet)

---

Top Contributors

[![thomasschiet](https://avatars.githubusercontent.com/u/286026?v=4)](https://github.com/thomasschiet "thomasschiet (19 commits)")

### Embed Badge

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

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

###  Alternatives

[wa72/htmlpagedom

jQuery-inspired DOM manipulation extension for Symfony's Crawler

3484.1M35](/packages/wa72-htmlpagedom)[php-tui/term

comprehensive low level terminal control

451.0M1](/packages/php-tui-term)[atelierdisko/coupon_code

PHP library to generate and validate coupon code strings.

62198.0k2](/packages/atelierdisko-coupon-code)

PHPackages © 2026

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