Hi
On 2026-10-06 11:17, [email protected] 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
