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

Hi On 2026-10-06 11:17, marc@mabe.berlin wrote:

I think the following points still need some discussion. Some of them may overlap with things others have already raised in this thread. Rather than replying to each of those messages separately, I've collected everything in this one mail and mention who brought a point up where it applies.

Thank you for the review. Derick and I already discussed some, but not all of the points. For now I'll just reply to those that are resolved to get them out of the way.

4. Configurable clock resolution I'd like a way to configure the resolution, e.g. a SystemClock that only ever returns whole seconds. Many consumers (JWT iat/exp, HTTP dates, database columns) never want fractions. A clock configured that way guarantees whole seconds to every consumer it is injected into, instead of each consumer having to truncate on its own. It also makes test expectations simpler, because the values never carry fractions.

We believe this is the job of a “Clock decorator”, e.g. CoarseClock that takes in some clock and appropriately rounds or truncates the Instant to the desired precision. Such a decorator would automatically be compatible with any type of clock (e.g. a FrozenClock for testing). 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.

7. get vs to The RFC explicitly states that the Unix timestamp is not the internal representation. getUnixTimestamp() is therefore a conversion, and by the RFC's own convention (toIso8601DateTimeString(), DateTime::toInstant()) it should be toUnixTimestamp(). Duration exposes its components as properties, so with get*() we'd end up with a third style within the same family.

Good catch, we renamed the methods to use the to prefix.

9. getNanoseconds() It isn't obvious whether this returns the nanoseconds since epoch or the nanoseconds within the current second. getNanoOfSecond() (Java's NANO_OF_SECOND) would remove that ambiguity.

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. 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. Best regards Tim Düsterhus