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

Hi On 2026-10-09 08:20, marc@mabe.berlin wrote:

As with the testing clocks, we consider a CoarseClock out of scope for this RFC. With a possible future truncateTo() that I already mentioned elsewhere in the discussion, a userland implementation would become trivial for the use cases where a coarser clock is required.

Fine by me to keep it out of scope for this RFC. For a future RFC, though, I'd prefer a built-in CoarseSystemClock over a generic decorator. A decorator always has to read the precise clock first and only then truncates, so it can never be cheaper than the clock it wraps. A built-in system clock configured for second (or millisecond) resolution could read a coarse clock source directly instead, such as CLOCK_REALTIME_COARSE on Linux.

Fair enough regarding the performance argument. I was specifically thinking about use cases where truncating to whole seconds is required. I've added a “CoarseSystemClock” to the possible future scope list. Having it as a separate class makes sense to me to make using the coarse system clock a very explicit and deliberate choice. The correct default for the majority of use cases is the SystemClock, the coarse clock potentially doesn't even have millisecond resolution depending on your configured tick rate, isn't necessarily aligned to second boundaries and …

On Linux arm64 I measured:

  clock_gettime(CLOCK_REALTIME)          13.3 ns
  clock_gettime(CLOCK_REALTIME_COARSE)    3.3 ns

… 10 nanoseconds is likely not all that much compared to the overhead that PHP adds (e.g. object allocation).

We believe that with the renaming of the “Unix timestamp” converter to use the to prefix and the lack of “Unix” in the name of getNanoseconds() the naming is clear enough. It is also easy to see that the result of getNanoseconds() can't be the number of nanoseconds elapsed since the Unix epoch, because the value is guaranteed to be less than 1_000_000_000 (i.e. less than 1 second). Using nanoseconds as the fractional part is consistent with Duration::$nanoseconds.

I'm not convinced yet […] getNanoOfSecond() removes the ambiguity entirely, at the cost of a few characters. If that's too far from the existing naming, getNanosecond() would at least match DateTime::getMicrosecond().

I'll put this on my list with Derick.

For completeness I'd like to note that the epoch of the Instant is intentionally left unspecified and that the Unix epoch is just one of several possible epochs.

Agreed, and that's exactly the point I made about "follows POSIX time": if the epoch and the representation are unspecified, the class definition shouldn't state that Instants follow POSIX time. That belongs to the Unix timestamp conversion methods.

See my reply in https://news-web.php.net/php.internals/132953. Best regards Tim Düsterhus