Re: [PHP-DEV] 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 (<[email protected]>)
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:[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                          |
> +---------------------------------------------------------------------+
>
>