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

On Tue, Oct 6, 2026, at 4:17 AM, marc@mabe.berlin wrote: > 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. I agree with this. $foo->toBar() is a very common "type conversion" pattern, and it makes sense to use here as well. > 8. getUnixTimestamp() / getUnixTimestampMilliseconds() > > Only the milliseconds variant names its unit, and microseconds (used all > over PHP: microtime(), DateTime) and nanoseconds are missing entirely. A > single pair taking the unit as an argument would cover all of them and > stay symmetric: > > public static function fromUnixTimestamp(int $timestamp, TimeUnit > $unit = TimeUnit::Second): self; > public function toUnixTimestamp(TimeUnit $unit = TimeUnit::Second): > int; > > TimeUnit would be an enum of Second, Millisecond, Microsecond and > Nanosecond, rounding towards negative infinity as already specified. The > current fromUnixTimestampSeconds($seconds, $nanoseconds) could remain alongside. I would agree here as well. > 13. A dedicated parser/formatter instead > > I'd prefer parsing and formatting to live in a dedicated parser/formatter > API (future scope) rather than on Instant, where it would sit next to the > other ISO-8601 profiles and custom patterns. If the pair stays on Instant, > the name should say what it really is (a fixed RFC 3339-like profile), and > the grammar should be part of what we vote on. I understand the tidiness/purity argument here, and I am generally sympathetic to it. However, that always needs to be balanced against usability. Any incoming date/time information to the PHP process is likely to be either an ISO-8601 string or a unix timestamp int. If we want people to convert those into Instants for doing manipulation and comparison on (which I presume is the case), then that needs to be ergonomically easy to do. Having to go through multiple parser/converter objects (which some purist is likely to insist be injected from a container rather than instantiated directly; I have been known to be that purist) to get there is not ergonomic. So if that logic is split off, we would need to be very careful to ensure the result is ergonomically simple and readily copy-pasteable. > 14. until() vs Duration::between() > > Was Duration::between(Instant $a, Instant $b) considered? Calculating a > duration feels like Duration's responsibility to me. This also seems reasonable, as a named constructor of Duration. --Larry Garfield