php / php/php-src

Add a UTC-normalizing DateTime method for ISO 8601 output

未关闭
#23,491 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

Feature Status: Needs Triage
主要语言
C
星标
40.4k
派生
8.2k
平均合并
2 天 15 小时
30 天内合并 PR
103

描述

Update: Based on feedback, this proposal no longer focuses on adding a
format constant. The preferred direction under discussion is a method that
normalizes the represented instant to UTC and returns ISO 8601 output with
millisecond precision and a Z suffix. Check this comment : https://github.com/php/php-src/issues/23491#issuecomment-5464152132

Spoiler old proposal ## Description

PHP provides predefined date format constants such as DATE_ISO8601,
DATE_ATOM, DATE_RFC3339, and DATE_RFC3339_EXTENDED. There is no predefined
format for the UTC timestamp commonly produced by JavaScript:

1970-01-01T00:00:00.000Z

For example:

new Date(0).toISOString();
// "1970-01-01T00:00:00.000Z"

Proposal

Add a predefined format for ISO 8601 timestamps with millisecond precision.

One possible name is:

DATE_ISO8601_MILLISECONDS_UTC
DateTimeInterface::ISO8601_MILLISECONDS_UTC

with the format string:

"Y-m-d\\TH:i:s.v\\Z"

The name and API shape are open for discussion.

An alternative is an offset-preserving format:

DATE_ISO8601_MILLISECONDS
DateTimeInterface::ISO8601_MILLISECONDS

using:

"Y-m-d\\TH:i:s.vP"

Example

$date = new DateTimeImmutable('@0');

echo $date->setTimezone(new DateTimeZone('UTC'))
    ->format(DATE_ISO8601_MILLISECONDS_UTC);

// 1970-01-01T00:00:00.000Z

As with the existing date format constants, formatting does not change the
timezone of the DateTime object. The caller must convert it to UTC before
using the _UTC format.

Existing constant

DATE_RFC3339_EXTENDED already includes milliseconds, but produces an offset:

1970-01-01T00:00:00.000+00:00

This is semantically equivalent to Z for UTC, but is not byte-for-byte
compatible with JavaScript's Date.prototype.toISOString().

Related discussion

PHP issue #14593 discusses the
interpretation of the Z suffix when parsing DateTime values. That issue is
about parsing and timezone representation; this proposal is about predefined
formatting constants in ext/date.

Questions

  • Is a millisecond-precision constant useful in addition to
    DATE_RFC3339_EXTENDED?
  • Should the format preserve the object's offset, or provide the Z form for
    UTC-normalized values?
  • What name and API shape should be used?
  • Would both forms introduce unnecessary overlap with the existing constants?

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先查看现有的日期格式化常量以及 ext/date 中 DateTime 的行为,尤其是 DATE_RFC3339_EXTENDED 和 UTC 转换。阅读链接的评论以了解首选的方法方向;当 API 形态达成一致,并且该方法生成具有毫秒精度和 Z 后缀、已规范化为 UTC 的 ISO 8601 输出时,即表示完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
php
领域
backend
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
活跃
描述清晰度
基本清楚
新手友好度
45/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。