Re: [RFC] Time\Instant and Time\Clock

Hi On 2026-10-04 16:04, Mirco Babin wrote:

Can an extra explanation be added in the introduction near the aforementioned RFC paragraph? Something like: A \Time\Instant can be viewed as a replacement for the Unix-Epoch-int. With the difference that the base-date might not be 1970-01-01. And with the difference that the \Time\Instant can have more precision in the form of milliscondes, microseconds, nanoseconds. The base-date and extra precision are an implementation detail and not described further. This also means the full timerange of the \Time\Instant is at least that of the Unix-Epoch-int, but can be extended in the future.

I'll put adding a clarification on my list for the next RFC update.

[…] At some point in the future time, one of the 4 libraries switches to \Time\SystemClock. Let's assume it is Beta that adapts. How is this code then going to look?

<?php
//
// Modified theoretical PSR-20-application
//

function AFunctionOfTheApplication()
{
    // $clock might also come from a Dependency Injection container.
    // Or be injected via parameters or via constructor injection.
    // It doesn't really matter.
    $clock = new MyApp_Clock();

    // The $clock is injected into external libraries. These
    // libraries are not under the control of the application.
    // Also the libraries do not use the Dependency Injection
    // container of the application. Otherwise the DI container
    // would have beeen provided as parameter instead of the
    // \Psr\Clock\ClockInterface.
    $result1 = Library_Alfa_Do_Something($clock);

    // Or use the provided Psr20ToNative adapter.
    $clockInstant = new \Time\SystemClock();
    $result2 = Library_Beta_Do_Something($clockInstant);

    $result3 = Library_Gamma_Do_Something($clock);

    $result4 = Library_Theta_Do_Something($clock);
}
?>

I hope the pattern becomes clear. After the \Time\Clock fact the PSR-20-application will be split in 2 clocks. Carefully selecting the right clock for the right call. And the careful selection has to take place on every update of any external library. Because the external library might have switched to \Time\Clock at any moment. This is a maintenance disaster.

The expectation is that you would use one of the two adapters to translate between the PSR-20 clock and PHP’s native clock, depending on which one is the source of truth in your application. The resulting code would look like this:

    function AFunctionOfTheApplication()
    {
        $clock = new MyApp_Clock();

        // The PSR-20 clock is the canonical one for this application,
        // create the native adapter.
        $nativeClock = new Psr20ToNative($clock);

        $result1 = Library_Alfa_Do_Something($clock);

        $result2 = Library_Beta_Do_Something($nativeClock);

        $result3 = Library_Gamma_Do_Something($clock);

        $result4 = Library_Theta_Do_Something($clock);
    }

This is one extra line to initialize the $nativeClock adapter and one changed line to pass the native clock to Beta instead of the PSR-20 clock.

But because the \Time\Clock->now() conflicts, as I have demonstrated, with the \Psr\Clock\ClockInterface->now(), this one-time solution is not possible. Now assume this PSR-20-application is a big one, thousands of classes, millions line of code. This will become a PSR-20-application maintenance disaster.

As Larry noted, changing from PSR-20 to the new date and time API would be a breaking change. This kind of migration would also not be limited to just the change in clocks. The Time\Instant, and the modeling of the new date and time API in general are not a drop-in replacement for the existing DateTimeImmutable API. A library that migrates from PSR-20 to the native clock will want to consistently use the date and time API to benefit from it. This will affect internal calculations and possibly returned values (e.g. returning an Instant where previously a DateTimeImmutable was returned). Just replacing the clock and keeping everything else the same brings little benefit. Changing the clock you pass in is the smallest part of the migration effort. Best regards Tim Düsterhus