Everything

php

Was deprecation of DATE_RFC7231 and DateTimeInterface::RFC7231 a mistake?

php.internals

Kamil Tekiela

223 days ago

Hi All,

I was one of the yes-voters for the
https://wiki.php.net/rfc/deprecations_php_8_5#deprecate_date_rfc7231_and_datetimeinterfacerfc7231
however, I would like to change my vote to no now.

The explanation for the deprecation wasn't very clear, and I feel I
was slightly misled by it.  It claims that the constant was
implemented by mistake, but I don't think that was the case.

DATE_RFC7231 follows the timestamp specification from the HTTP format.
It has been repeated by the current RFC 9110
https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7
The GMT part isn't a mistake; it's hardcoded as part of the format.
Thus, the constant is implemented correctly in PHP.

It's true that this could lead to unexpected results when you format a
DateTime that isn't in UTC, but that's a programmer mistake and not
the fault of the constant. The format is timezone agnostic so it's the
responsibility of the programmer to ensure the DateTime object is in
UTC before formatting.

Users are now faced with having to replace the constant with its
string value, despite the constant having a well-defined use and
producing correct and "wanted" results. This is more error-prone than
accidentally forgetting to call setTimezone(DateTimeZone::UTC).
Deprecating this constant hasn't improved anything for PHP users and
only made things worse.

What do you think? Should we undeprecate these constants?

Regards,
Kamil Tekiela

Derick Rethans

223 days ago

Hi,

On Wed, 21 Jan 2026, Kamil Tekiela wrote:

> I was one of the yes-voters for the
> https://wiki.php.net/rfc/deprecations_php_8_5#deprecate_date_rfc7231_and_datetimeinterfacerfc7231
> however, I would like to change my vote to no now.
>
> The explanation for the deprecation wasn't very clear, and I feel I
> was slightly misled by it.  It claims that the constant was
> implemented by mistake, but I don't think that was the case.
>
> DATE_RFC7231 follows the timestamp specification from the HTTP format.
> It has been repeated by the current RFC 9110
> https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7 The GMT part
> isn't a mistake; it's hardcoded as part of the format. Thus, the
> constant is implemented correctly in PHP.

No, it wasn't. It would format according to local time and just add
"GMT" to the end:
https://www.php.net/manual/en/class.datetimeimmutable.php (docs haven't
been updated for it).

> It's true that this could lead to unexpected results when you format a
> DateTime that isn't in UTC, but that's a programmer mistake and not
> the fault of the constant. The format is timezone agnostic so it's the
> responsibility of the programmer to ensure the DateTime object is in
> UTC before formatting.

Formatters are *only* for local time, and do not currently have the
possibility to change the timezone to UTC. So I disagree, as people
rightfully should have expected PHP to handle a specific pre-cooked
format to behave as the RFC that is named after ought to behave.

> Users are now faced with having to replace the constant with its
> string value, despite the constant having a well-defined use and
> producing correct and "wanted" results. This is more error-prone than
> accidentally forgetting to call setTimezone(DateTimeZone::UTC).
> Deprecating this constant hasn't improved anything for PHP users and
> only made things worse.
>
> What do you think? Should we undeprecate these constants?

No, I don't believe we should put them back as they were.

I can think of two possible ways:

1. We could think about adding specific formatting *methods*, such as
"asRfc7231String()".

This would allow for it to handle the timezone "fix" and also return the
right format. Constants aren't the way forwards here. But that also means,
that we probably should have methods for other useful formats /
specifications too.

2. Create a new formatting specifier which has a specfic meaning to set the
timezone to UTC when used at the beginning of the string, say "-".

There is some precedent with special formatting letters with
DateTimeImmutable::createFromFormat.

The constant value then could be "-D, d M Y H:i:s \\G\\M\\T"

I don't really like either of these though.

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support

mastodon: @derickr@phpc.social @xdebug@phpc.social

Tim Düsterhus

223 days ago

Hi

Am 2026-01-21 15:47, schrieb Derick Rethans:

> possibility to change the timezone to UTC. So I disagree, as people
> rightfully should have expected PHP to handle a specific pre-cooked
> format to behave as the RFC that is named after ought to behave.

I agree with Derick's entire email, but particularly this part:

Providing some helper constant that requires you to perform an important
“extra step” with nothing forcing you to perform that extra step and
where not performing that extra step will result in behavior that is
subtly incorrect is dangerous API design. The further away from UTC your
“default timezone” is, the more wrong will the results be. This can have
significant consequences on the behavior of your application, e.g.
cookies expiring too soon or too late and confusing HTTP caching
behavior.

Best regards
Tim Düsterhus

Andreas Heigl

223 days ago

Hey all

On 21.01.26 13:09, Kamil Tekiela wrote:

> Hi All,
>
> I was one of the yes-voters for the
> https://wiki.php.net/rfc/deprecations_php_8_5#deprecate_date_rfc7231_and_datetimeinterfacerfc7231
> however, I would like to change my vote to no now.
>
> The explanation for the deprecation wasn't very clear, and I feel I
> was slightly misled by it.  It claims that the constant was
> implemented by mistake, but I don't think that was the case.
>
> DATE_RFC7231 follows the timestamp specification from the HTTP format.
> It has been repeated by the current RFC 9110
> https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7
> The GMT part isn't a mistake; it's hardcoded as part of the format.
> Thus, the constant is implemented correctly in PHP.
>
> It's true that this could lead to unexpected results when you format a
> DateTime that isn't in UTC, but that's a programmer mistake and not
> the fault of the constant. The format is timezone agnostic so it's the
> responsibility of the programmer to ensure the DateTime object is in
> UTC before formatting.

While most of the time being the same, there are some very distinct
differences between GMT and UTC. As RFC7231 explicitly requests GMT I'd
even reject formatting a DateTime-object that has been set to UTC.

IMO if someone relies upon it, they can very easily create a userland
piece of code that formats any DateTimeImmutable correctly as RFC7231
date like in https://3v4l.org/WZv34#v8.4.14

That is much easier and will always get the user the result they want.
Adding such a function for each and every edge-case to the PHP-Core
seems overkill.

>
> Users are now faced with having to replace the constant with its
> string value, despite the constant having a well-defined use and
> producing correct and "wanted" results. This is more error-prone than
> accidentally forgetting to call setTimezone(DateTimeZone::UTC).
> Deprecating this constant hasn't improved anything for PHP users and
> only made things worse.
>
> What do you think? Should we undeprecate these constants?

Nope! But add a comment to the deprecation information on the docs at
PHP.net

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

Tim Düsterhus

223 days ago

Hi

Am 2026-01-21 16:17, schrieb Andreas Heigl:

> As RFC7231 explicitly requests GMT I'd even reject formatting a
> DateTime-object that has been set to UTC.

Quoting from RFC 9110#5.6.7:

> An HTTP-date value represents time as an instance of Coordinated
> Universal Time (UTC).

Best regards
Tim Düsterhus

Andreas Heigl

223 days ago

On 21.01.26 16:33, Tim Düsterhus wrote:

> Hi
>
> Am 2026-01-21 16:17, schrieb Andreas Heigl:
>> As RFC7231 explicitly requests GMT I'd even reject formatting a
>> DateTime-object that has been set to UTC.
>
> Quoting from RFC 9110#5.6.7:
>
>> An HTTP-date value represents time as an instance of Coordinated
>> Universal Time (UTC).

In all fairness: It is really hard for me to take someone serious that
is posting this:

And I am also quoting from RFC 9110#5.6.7

"The first two formats indicate UTC by the three-letter abbreviation for
Greenwich Mean Time, "GMT", a predecessor of the UTC name;"

That is about the same as saying "Prices are indicated in Euro by the
three-letter abbreviation for US-Dollar, 'USD', a predecessessor of the
EUR name"

Anyhow! This is a technicallity that in most cases is irrelevant and
does not invalidate the rest of the message

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

Rowan Tommins [IMSoP]

223 days ago

On 21 January 2026 15:59:50 GMT, Andreas Heigl <andreas@heigl.org> wrote:

>That is about the same as saying "Prices are indicated in Euro by the three-letter abbreviation for US-Dollar, 'USD', a predecessessor of the EUR name"

That is a gross exaggeration. Wikipedia summarises it like this:

> English speakers often use GMT as a synonym for UTC. For navigation, it is considered equivalent to UT1 (the modern form of mean solar time at 0° longitude); but this meaning can differ from UTC by up to 0.9 s. The term "GMT" should thus not be used for purposes that require precision.

The format we're talking about does not have fractional seconds, so we're talking about a potential difference of 1 second between different interpretations of what "GMT" could mean.


Rowan Tommins
[IMSoP]

Tim Düsterhus

223 days ago

Hi

Am 2026-01-21 16:59, schrieb Andreas Heigl:

>> Quoting from RFC 9110#5.6.7:
>>
>>> An HTTP-date value represents time as an instance of Coordinated
>>> Universal Time (UTC).
>
> In all fairness: It is really hard for me to take someone serious that
> is posting this:
>
> […]
>
> Anyhow! This is a technicallity that in most cases is irrelevant and
> does not invalidate the rest of the message

The correct recipients of this complaint are the editors of RFC 9110,
not PHP Internals.

Best regards
Tim Düsterhus