Re: [PHP-DEV] 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:[email protected]                  N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org                                           |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas                               |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg                          |
+---------------------------------------------------------------------+