Re: Add ISO 8601 date format constant with millisecond precision

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 | +---------------------------------------------------------------------+