PHP: rfc:time_instant_class

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Time\Instant and Time\Clock ======
  * Version: 1.0
  * Date: 2026-09-21
  * Author: Tim Düsterhus, tim@tideways-gmbh.com, Derick Rethans, derick@php.net
  * Status: Draft
  * Implementation: https://github.com/...
  * Discussion thread: https://news-web.php.net/php.internals/…
  * Voting thread: tbd

===== Introduction =====

The [[duration_class|Duration class]] RFC added <php>Time\Duration</php> to PHP 8.6, a structured representation of a “stop-watch” duration as the first part of a modern date and time API. While knowing how long something took is already valuable, in many cases it is also important to know at which point on the timeline of the universe the measurement started.

PHP currently offers two ways to represent such a point, and both are unsatisfying for the general case. A plain <php>int</php> as returned by <php>time()</php> discards all sub-second precision and carries no type information, leaving the question of “is this seconds, milliseconds or something entirely different” to documentation instead of the type system. <php>DateTimeImmutable</php> carries a timezone and a full calendar representation, which means a value that is conceptually just “this moment” carries along information about calendars and clocks that is frequently irrelevant, occasionally wrong, and always something the reader has to reason about to not introduce any errors during time handling.

This RFC proposes the addition of a <php>Time\Instant</php> class representing an absolute point on the timeline of the universe together with a <php>Time\Clock</php> interface and a <php>Time\Clock\SystemClock</php> implementation for obtaining the current <php>Time\Instant</php>.

<PHP>
<?php

use Time\Clock\SystemClock;
use Time\Instant;

$clock = new SystemClock();

$now = $clock->now();
$moonLanding = Instant::fromIso8601DateTimeString('1969-07-20T20:17:40Z');

printf("It's been %d seconds since the moon landing\n", $moonLanding->until($now)->seconds);

?>
</PHP>

===== Proposal =====

Add a new always-available class <php>Time\Instant</php> representing a “point in time” together with an interface <php>Time\Clock</php> and a <php>Time\Clock\SystemClock</php> implementation.

<PHP>
<?php

namespace Time
{
    /**
     * An absolute point on the wall-clock timeline with nanosecond precision.
     * It is independent of any timezone.
     *
     * Wall-clock time is not monotonic: it may jump forwards or backwards due to
     * NTP adjustments or manual changes. Instant is therefore unsuitable for
     * measuring elapsed time.
     *
     * Instants follow POSIX time and do not account for leap seconds.
     *
     * The representable range is unspecified. Any operation that leaves this
     * range will throw a Time\TimeException.
     *
     * The internal representation and the origin it is relative to are not part
     * of the public API.
     *
     * @strict-properties
     */
    final readonly class Instant
    {
        /**
         * Create an instant from a Unix timestamp. $nanoseconds must be between
         * 0 and 999_999_999 and always advances the instant, including for
         * negative values of $seconds.
         *
         * On 32-bit platforms PHP’s int range limits this constructor to the
         * years 1901 to 2038.
         *
         * @throws \ValueError If $nanoseconds is not between 0 and 999_999_999.
         */
        public static function fromUnixTimestamp(int $seconds, int $nanoseconds = 0): self {}

        /**
         * Create an instant from a Unix timestamp in milliseconds.
         *
         * On 32-bit platforms PHP’s int range limits this constructor to roughly
         * 24 days around the Unix epoch.
         */
        public static function fromUnixTimestampMilliseconds(int $milliseconds): self {}

        /**
         * Parse an ISO-8601 date and time string. A zone offset is required.
         *
         * @throws TimeException If $specification is not accepted by the parser,
         *                       or carries no zone offset.
         * @throws TimeException If the denoted instant is outside the
         *                       representable range.
         */
        public static function fromIso8601DateTimeString(string $specification): self {}

        /**
         * The instant at which the Unix epoch began, equivalent to
         * `fromUnixTimestamp(0)`.
         */
        public static function unixEpoch(): self {}

        /**
         * The whole seconds elapsed since the Unix epoch, rounded towards
         * negative infinity (RoundingMode::NegativeInfinity). The discarded
         * fractional part is available via ->getNanoseconds().
         *
         * On 32-bit platforms this is representable only for the years 1901 to
         * 2038.
         *
         * @throws TimeException If the value is not representable as an int on
         *                       the current platform.
         */
        public function getUnixTimestamp(): int {}

        /**
         * The whole milliseconds elapsed since the Unix epoch, rounded towards
         * negative infinity (RoundingMode::NegativeInfinity).
         *
         * On 32-bit platforms this is representable only within roughly 24 days
         * around the Unix epoch.
         *
         * @throws TimeException If the value is not representable as an int on
         *                       the current platform.
         */
        public function getUnixTimestampMilliseconds(): int {}

        /**
         * The sub-second fraction of this instant, between 0 and 999_999_999.
         */
        public function getNanoseconds(): int {}

        /**
         * Add the given duration to this instant. A negative duration moves the
         * instant backwards.
         *
         * @return self $this + $duration
         *
         * @throws TimeException If the result is outside the representable range.
         */
        public function add(Duration $duration): self {}

        /**
         * Subtract the given duration from this instant. A negative duration
         * moves the instant forwards.
         *
         * @return self $this - $duration
         *
         * @throws TimeException If the result is outside the representable range.
         */
        public function sub(Duration $duration): self {}

        /**
         * The duration elapsed from this instant until the given instant. The
         * result is negative if $instant precedes this instant.
         *
         * @return Duration $instant - $this
         *
         * @throws TimeException If the difference exceeds the range of
         *                       Time\Duration.
         */
        public function until(self $instant): Duration {}

        /**
         * Returns -1, 0, 1 if $a is earlier than, equal to, or later than $b
         * respectively.
         */
        public static function compare(self $a, self $b): int {}

        /**
         * Returns an ISO-8601 date and time string with the 'Z' zone designator.
         *
         * Years outside 0000 to 9999 use the expanded representation with a
         * mandatory sign.
         */
        public function toIso8601DateTimeString(): string {}
    }

    interface Clock
    {
        /**
         * The current instant, at the resolution offered by the underlying clock.
         */
        public function now(): Instant;
    }
}

namespace Time\Clock
{
    /**
     * Reads the system's wall clock.
     *
     * @strict-properties
     */
    final readonly class SystemClock implements \Time\Clock
    {
        public function __construct() {}

        /**
         * The current instant, at the resolution offered by the platform clock,
         * which is generally coarser than nanoseconds.
         *
         * Returned values are not guaranteed to be monotonically increasing
         * across calls.
         */
        public function now(): \Time\Instant {}
    }
}

?>
</PHP>

Just like <php>Time\Duration</php>, the <php>Time\Instant</php> class will implement internal “comparison handlers”, which means that direct comparisons with operators such as <php><</php> or <php><=></php> will work. Other operators (such as <php>+</php> for addition) will not be overloaded.

Debug representations (e.g. using <php>var_dump()</php>) of <php>Time\Instant</php> will show the ISO-8601 representation, since it is both human readable and the only format capable of representing every possible point in time the class can represent.

Serialization of <php>Time\Instant</php> will be supported, the exact format is considered an implementation detail.

==== Design Considerations ====

=== Time\Instant ===

An <php>Time\Instant</php> carries no timezone. It represents a unique point on the timeline of the universe. This point is the same for everyone, no matter where they are located on the Earth (or not even of the Earth), i.e. no matter their timezone.

This means that arbitrary formatting of an <php>Time\Instant</php> is unsupported, since that requires knowledge of a timezone. Combining an instant with a timezone to allow these “time as specified on calendar and clock” operations is left for a different class that is left to future scope.

For the same reason the internal representation of <php>Time\Instant</php> is intentionally left unspecified and there are deliberately no public properties. In particular the “Unix timestamp” is not the primary representation. Reasons for this are that across programming languages and computer science in general the representation of time differs. There are multiple equally valid epochs (e.g. the Unix epoch on 1970-01-01, but also 1900-01-01, 2000-01-01, 0000-01-01, and others) and resolution also differs, even where the Unix timestamp is the primary representation. Instead the <php>Time\Instant</php> should be capable of representing arbitrary points in time, without being limited by integer precision (particularly for 32-bit PHP). Constructors for these additional epochs or representations are left to future scope. The RFC ships with ISO-8601 as the universal representation and Unix timestamps, acknowledging its wide usage in practice.

Similarly, since the “timeline of the universe” does not know about days, or months, the only meaningful mathematical operations are moving backwards and forwards on the timeline by a number of (fractional) seconds - and calculating the distance between two points, which is exactly what the <php>Time\Duration</php> class represents. Moving by “a month” is an operation that will be supported by the aforementioned future scope class that knows about timezones.

Following the lead of virtually all programming languages and operating systems, leap seconds are ignored. This means that ISO-8601 strings representing a leap second (<php>23:59:60</php>) are rejected as unrepresentable and the duration returned by <php>->until()</php> for two instants separated by a leap second is one second short of the actual time elapsed.

The exact representable range is unspecified and will be left to implementation constraints. It will be capable of at least representing all instants that <php>DateTimeImmutable</php> is capable of representing. This also means that the time between two instants will be able to exceed the range of <php>Time\Duration</php>. Future PHP versions may increase the supported range, but may not decrease it.

The ISO-8601 parser (<php>fromIso8601DateTimeString()</php>) is strict: It will only accept well-formed inputs, but may not support all legal formats. Specifying a timezone is required, PHP’s default timezone will not be used, since this would effectively invent information out of thin air. Support for additional formats may be added in future PHP versions by a simple pull request.

The <php>fromUnixTimestampMilliseconds()</php> constructor and <php>getUnixTimestampMilliseconds()</php> getter is provided for interoperability with programming languages using Unix timestamps with millisecond precision, in particular JavaScript.

=== Time\Clock\SystemClock ===

While <php>Time\Instant</php> supports nanosecond precision, matching the precision of <php>Time\Duration</php> to allow for all mathematical operations to have well-defined results, the precision provided by the operating system’s clock is generally much lower and dependent on the operating system.

Even though the timeline of the universe can only go forward and ticks at the same speed, the same is not true for the operating system clock: The internal clock in computers is not perfectly precise and might tick too fast or too slow, requiring regular adjustments to match reality (e.g. using NTP). During those adjustments the clock may make large jumps or may even move backwards. Users must be prepared that an instant B obtained after another instant A might be smaller than instant A with the <php>Time\Duration</php> returned by <php>until()</php> being negative, making it unsuitable to measure elapsed time. Measuring elapsed time using the monotonic clock (which only ticks forward) will be left to future scope.

=== Time\Clock ===

Obtaining the current time is likely the most common case for otherwise pure code to become impure and untestable. Following best practices in the ecosystem a <php>Time\Clock</php> interface is provided to allow injecting purpose-built clocks for testing purposes and related use cases without needing to wrap the <php>Time\Clock\SystemClock</php> in a custom class implementing a userland interface. The native interface will also enable future use cases of exchangeable clocks in internal APIs.

The RFC intentionally does not provide any clocks besides the system clock, since possible implementations for test clocks differ wildly (e.g. always return a fixed instant, moving the instant forward for every call, increasing or decreasing resolution) with purpose-built userland implementations providing more flexibility than internal implementations could.

==== Examples ====

<PHP>
<?php
 
use Time\Clock;
use Time\Duration;
use Time\Instant;
 
final class TokenValidator
{
    public function __construct(
        private readonly Clock $clock,
        private readonly Duration $validityPeriod,
    ) {}
 
    public function isValid(Instant $issuedAt): bool
    {
        return $this->clock->now() < $issuedAt->add($this->validityPeriod);
    }
}
 
?>
</PHP>

<PHP>
<?php
 
use Time\Clock;
use Time\Duration;
use Time\Instant;

final class FrozenClock implements Clock
{
    public function __construct(
        private Instant $now,
    ) {}
 
    public function now(): Instant
    {
        return $this->now;
    }
 
    public function advance(Duration $duration): void
    {
        $this->now = $this->now->add($duration);
    }
}
 
$clock = new FrozenClock(Instant::fromIso8601DateTimeString('2026-09-21T12:00:00Z'));
$issuedAt = $clock->now();
 
$validator = new TokenValidator($clock, Duration::fromMinutes(30));

$clock->advance(Duration::fromMinutes(15));

var_dump($validator->isValid($issuedAt)); // true
 
$clock->advance(Duration::fromMinutes(20));
 
var_dump($validator->isValid($issuedAt)); // false
 
?>
</PHP>

<PHP>
<?php

use Time\Instant;

$now = Instant::fromIso8601DateTimeString('2026-09-21T12:00:00Z');

$moonLanding = Instant::fromIso8601DateTimeString('1969-07-20T20:17:40Z');
$startOfGregorianCalendar = Instant::fromIso8601DateTimeString('1582-10-15T00:00:00Z');

// fine, roughly 57 years
$elapsed = $moonLanding->until($now);

// throws TimeException, roughly 444 years and well outside the range of Time\Duration
$startOfGregorianCalendar->until($now);

?>
</PHP>

===== Backward Incompatible Changes =====

This RFC is only proposing three new symbols, all within the <php>Time\</php> namespace that was reserved for the new date/time API as part of the [[duration_class|Duration class]] RFC for PHP 8.6. Generally adding new symbols is not considered a breaking change.

===== Proposed PHP Version(s) =====

Next minor (8.7).

===== RFC Impact =====

==== To the Ecosystem ====

The proposed <php>Time\Clock</php> interface is a direct replacement of PSR-20’s <php>Psr\Clock\ClockInterface</php>, except that it returns a timezone-less instant instead of a <php>DateTimeImmutable</php>. The ecosystem might want to build a Clock that translates between <php>Time\Clock</php> and the PSR-20 <php>Psr\Clock\ClockInterface</php> while the process of migrating to the new <php>Time\Instant</php> is in progress.

==== To Existing Extensions ====

Extensions may want to adjust their API to take <php>Time\Instant</php> in addition to an <php>int</php> representing a Unix timestamp or an object implementing <php>DateTimeInterface</php>.

==== To SAPIs ====

None.

===== Open Issues =====

  * Shall we introduce more Exceptions now?

===== Future Scope =====

The next step after <php>Instant</php> will likely be adding a new timezone class together with a class that combines an instant with a timezone to allow printing dates and times in custom formats.

===== Voting Choices =====

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Implement Time\Instant and the clock(s) as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====
Links to proof of concept PR.

If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  * [[duration_class|PHP RFC: Duration class]]

===== Rejected Features =====



===== Changelog =====

  * 2026-09-21: Initial version.
Page Tools
