createFromFormat 怎样读取微秒时间

PHP 读取带微秒的时间字符串时，关键不是把小数点后的数字当成普通文本，而是在格式串中使用 u。例如输入 2026-10-25 14:08:09.123456，可以用 Y-m-d H:i:s.u 解析，再用 format('u') 取回六位微秒。官方手册地址：https://www.php.net/manual/en/datetimeimmutable.createfromformat.php。

实用写法是：输入有小数秒就把 .u 写进格式，带时区就把时区一并写入或显式传入；解析后同时判断返回值和 getLastErrors()，不要只看对象是否创建成功。

用 u 对齐带微秒的输入格式

u 表示微秒，最多接收 6 位。输入中的日期、时间、小数点和微秒位数必须与格式串的结构对应；缺少 u 时，微秒不会被正确纳入结果对象。

format('Y-m-d H:i:s.uP');
// 结果示意：2026-10-25 14:08:09.123456+08:00

这里的 ! 让未填写的字段从 Unix epoch 的零值开始，而不是偷偷继承当前日期。若输入只有日期和微秒时间，格式也要按实际字符串调整；不要为了“看起来完整”给输入拼接并不存在的字符。

用 ! 和 | 控制未填写字段

createFromFormat() 会从左到右解析。没有出现在格式中的部分可能使用当前日期时间；这在只解析时分秒、或者服务跨天运行时尤其容易造成隐蔽差异。

• ! 放在格式开头，会把所有字段重置到 Unix epoch，再应用后续格式。
• | 放在格式末尾，只把尚未解析的字段补成零值，已解析字段保留。
• 只解析时分秒时，建议明确写出重置策略，避免日期取自今天而不是业务约定日期。

format('Y-m-d H:i:s.u T');
// 结果示意：1970-01-01 14:08:09.123456 UTC

如果你的业务要求“保留已给出的日期、其余时间字段补零”，可以把 | 放在格式末尾，例如 Y-m-d|。这两个符号解决的是默认字段问题，不是微秒截断问题；微秒仍要由 u 明确接收。

时区要显式处理，不能依赖运行环境

当输入字符串没有包含时区时，如果第三个参数省略，PHP 会使用当前默认时区。开发机、容器和生产机的默认时区可能不同，因此日志或接口字段最好在格式串中带上偏移量，或者把 DateTimeZone 明确传给方法。

format('c');

如果输入是数据库中的“本地时间”而没有偏移量，应先约定它属于哪个时区，再传入对应的 DateTimeZone。解析成功不等于时区语义正确，时区属于输入契约的一部分。

同时处理失败、溢出和微秒输出

返回 false 表示格式无法解析；日期越界等情况可能先得到一个对象，同时留下 warning。生产代码不应只判断对象是否存在，还应在解析后读取 DateTimeImmutable::getLastErrors()。没有错误或警告时，该方法在部分 PHP 版本中可能返回 false，所以读取结果时要兼容这一形态。

 0 || $errors['error_count'] > 0)) {
    throw new InvalidArgumentException('日期文本存在溢出或格式错误');
}

// u 始终按六位微秒输出，不要用浮点数保存它。
echo $time->format('Y-m-d H:i:s.u');

微秒是时间对象的一部分，输出时使用 format('u') 或包含 u 的格式串。不要先转成浮点 Unix 时间戳再期待恢复原始六位微秒，浮点表示可能带来精度损失。

常见问题

输入只有三位毫秒，能用 u 吗？可以，u 接收最多六位小数秒，输出时会按微秒字段格式化；是否把毫秒补成六位，应由你的接口契约决定。

为什么解析成功但日期不对？通常是格式没有覆盖日期字段，且没有使用 ! 或 | 明确默认策略；也要检查输入是否带时区，以及第三个参数是否传入了预期时区。

把微秒读取拆成三件事即可稳定处理：格式串用 u 对齐小数秒，!/| 明确未填写字段，时区和错误结果显式检查。这样既能保留六位微秒，也能避免把默认日期、环境时区或日期溢出误当成有效数据。