Add ISO 8601 date format constant with millisecond precision

> Hi Andreas, > > Thank you for your feedback. > > I agree that a format constant containing a literal Z is not ideal because > the format string cannot enforce UTC. A userland formatter is safer because > it can normalize the value before formatting it. > > After considering this, I think an instance method may be a better fit than > a new format constant: > > $date->toISOString(); > > The method could normalize the instant to UTC and return exactly: > > 1970-01-01T00:00:00.000Z > > It would not modify the original object, which is particularly important for > DateTimeImmutable. > > I also found that Carbon provides: > > $date->toIso8601ZuluString('millisecond'); > > However, that requires an external dependency. My motivation is to provide > a dependency-free way to produce a common ISO 8601 UTC representation used > when exchanging timestamps between PHP, JavaScript, Java, Go, and other > ecosystems. > > I searched for an existing PHP issue or RFC proposing this exact method but > found only the older, inactive DateTime::__toString() RFC, which addressed > a different problem. > > Would you consider a UTC-normalizing instance method a more appropriate > direction for this issue than adding a format constant?

> > Best regards, > > Théo Attali > > El sáb, 29 ago 2026 a las 12:36, Andreas Heigl (<andreas@heigl.org>) > escribió: > >> Hey Théo >> >> On 29.08.26 11:47, Théo Attali wrote: >>> Hi ! >>> >>> Sorry derick for the duplicated email but I was not registered. >>> >>> This is my first contribution, so I would appreciate any help on the >>> proposal and on following the project's contribution process. >>> >>> I opened issue #23491 for a possible addition to ext/date: >>> >>> https://github.com/php/php-src/issues/23491 >>> >>> I would appreciate feedback before preparing an implementation. >>> >>> PHP currently provides DATE_RFC3339_EXTENDED, which includes millisecond >>> precision. For a UTC DateTime, it produces: >>> >>> 1970-01-01T00:00:00.000+00:00 >>> >>> Some applications need the equivalent representation with the ISO 8601 >> UTC >>> designator Z: >>> >>> 1970-01-01T00:00:00.000Z >>> >>> This is also the format produced by JavaScript's >>> Date.prototype.toISOString(): >>> >>> new Date(0).toISOString(); >>> // "1970-01-01T00:00:00.000Z" >>> >>> Would a predefined format for this representation be appropriate for >>> ext/date? >>> >>> One possible API would be: >>> >>> DATE_ISO8601_MILLISECONDS_UTC >>> DateTimeInterface::ISO8601_MILLISECONDS_UTC >>> >>> with the format string: >>> >>> "Y-m-d\\TH:i:s.v\\Z" >>> >>> For example: >>> >>> $date = new DateTimeImmutable('@0'); >>> echo $date->setTimezone(new DateTimeZone('UTC')) >>> ->format(DATE_ISO8601_MILLISECONDS_UTC); >>> >>> // 1970-01-01T00:00:00.000Z >>> >>> The name and API shape are open for discussion. Another option would be >> an >>> offset-preserving format: >>> >>> DATE_ISO8601_MILLISECONDS >>> DateTimeInterface::ISO8601_MILLISECONDS >>> >>> using: >>> >>> "Y-m-d\\TH:i:s.vP" >>> >>> I understand that date format constants only define formatting; they do >> not >>> change the timezone of the DateTime object. >>> A format containing a literal Z would therefore require the caller to >>> normalize the object to UTC first. >>> >>> For context, issue #14593 discusses the interpretation of the Z suffix >> when >>> parsing DateTime values: >>> >>> https://github.com/php/php-src/issues/14593 >>> >>> That issue concerns parsing and timezone representation, whereas this >>> proposal concerns predefined formatting constants. >>> >>> I would appreciate feedback on: >>> >>> 1. Whether a millisecond-precision format is useful in addition to >>> DATE_RFC3339_EXTENDED. >>> 2. Whether an offset-preserving format or a UTC-suffix format is >> preferable. >>> 3. Whether the proposed names follow the preferred ext/date convention. >>> 4. Whether an RFC is required before implementation. >>> >>> Thank you, >>> >>> Théo Attali >>> >> I see some serious issues with the idea of adding the format with the >> `\\Z` at the end as you already described. It would require a >> prerequisite that can'T be enforced and that will therefore cause a lot >> of confusion. >> >> To ease that confusion I would recommend anyone that has that explicit >> requirement to create a Formatter - perhaps tehr eeven is one already >> available that in essence just does something like this: >> >> class Formatter >> { >> public static function formatIso(DateTimeImmutable $date): string >> { >> return $date->setTimezone(new >> DateTimeZone('UTC'))->format('Y-m-d\\TH:i:s.vP'); >> } >> } >> >> Maintaining such a set of Formatters in Userland seems to be much easier >> than adding that in the PHP-Src. It would also make the formatter >> available to ALL PHP-Versions that have a DateTimeImmutable object and >> not only PHP8.6/8.7 onwards. >> >> From my side I would by now not add any more constants to the >> PHP-Source as they will not be available to earler versions. And I say >> that as the person that added the _EXTENDED constants... >> >> By now I would create a formatter in userland and promote that for usage >> as it's a small library that can be used by *any* PHP-Version that needs >> it. >> >> My 0.02€ >> >> Cheers >> >> Andreas >> -- >> ,,, >> (o o) >> +---------------------------------------------------------ooO-(_)-Ooo-+ >> | Andreas Heigl | >> | mailto:andreas@heigl.org N 50°22'59.5" E 08°23'58" | >> | https://andreas.heigl.org | >> +---------------------------------------------------------------------+ >> | https://hei.gl/appointmentwithandreas | >> +---------------------------------------------------------------------+ >> | GPG-Key: https://hei.gl/keyandreasheiglorg | >> +---------------------------------------------------------------------+ >> >> >