DateTime::createFromFormat

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — 根据给定的格式解析日期时间字符串

说明

面向对象风格

public static DateTime::createFromFormat(string $format, string $time, DateTimeZone $timezone = ?): DateTime

过程化风格

date_create_from_format(string $format, string $time, DateTimeZone $timezone = ?): DateTime

将 time 参数给定的日期时间字符串， 根据 format 参数给定的格式 解析为一个新的 DateTime 对象。

参数

format

在解析日期时间字符串的时候使用的格式 string。 参加下列的格式清单。 大部分格式和 date() 函数中的格式是一致的。

format 参数中支持的字符
format 中的字符 解释 示例
日 --- ---
d 和 j 一个月中的第几天，2 位数字表示，有前导 0 或者无前导 0 01 到 31 或者 1 到 31
D 和 l 星期几的文字表示 Mon 到 Sun 或者 Sunday 到 Saturday
S 2 个字母表示的一个月中的第几天（序数词）， 在进行解析的时候会被忽略 st，nd，rd 或者 th。
z 一年中的第几天，从 0 开始 0 到 365
月 --- ---
F 和 M 文本表示的月份，例如 January 或者 Sept January 到 December 或者 Jan 到 Dec
m 和 n 数值表示的月份，有前导 0 或者无前导 0 01 到 12 or 1 到 12
年 --- ---
Y 4 位数字表示的年 例如：1999 或 2003
y 2 位数字表示的年， 可用的范围是 1970 至 2069（不含） 例如： 99 或 03 （表示 1999 和 2003）
时间 --- ---
a 和 A 上午、下午 am 或 pm
g and h 12 小时制的小时，有前导 0 或者无前导 0 1 到 12 或者 01 到 12
G 和 H 24 小时制的小时，有前导 0 或者无前导 0 0 到 23 或 00 到 23
i 分钟，有前导 0 00 到 59
s 秒，有前导 0 00 到 59
u 微秒，最多到 6 位数字 示例：45，654321
时区 --- ---
e，O, P 和 T 时区名称，或者是以 UTC 时区为基准的小时偏移量， 或者是以 UTC 为基准的小时和分钟的偏移量， 小时和分钟之间用冒号（:）分隔。 示例：UTC，GMT， Atlantic/Azores 或 +0200 或 +02:00 或 EST，MDT
完整的日期和时间 --- ---
U 从 Unix Epoch (January 1 1970 00:00:00 GMT) 开始计算的时间，以秒为单位 示例：1292177455
空白字符和分隔字符 --- ---
（空格） 一个空格字符或者一个 tab 字符 示例：
# 可以是一下分隔符号中的任意一个： ;， :，/，.， ,，-，( 或 ) 示例：/
;， :，/，.， ,，-，( 或 ) 特殊字符 示例：-
? 随机字节 示例：^ （需要注意的是， 对于 UTF-8 字符，可能会需要多个 ?。 这种情况下，请使用 *）
* 随机字节，直到遇到下一个有效的分隔符号或者数值 示例：使用 Y-*-d 格式用来解析 2009-aWord-08 字符串的时候， * 会匹配 aWord
! 将所有的字段（年、月、日、时、分、秒、微秒以及时区）重置到 Unix Epoch 时间。 如果不使用 !, 格式， 那么所有的字段会被设置为系统当前的日期和时间。
| 将尚未被解析的字段，也即格式字符串中未明确指定的字段 （年、月、日、时、分、秒、微秒以及时区） 重置到 Unix Epoch 时间。 Y-m-d| 会解析日期时间字符串中的年、月和日， 但是对于时、分、秒字段会设置为 0.
+ 在格式字符串中使用这个格式表示字符， 并且所提供的日期时间字符串中包含除了格式字符之外的其他数据的话，不会发出一个错误，而是发出一个警告。 使用 DateTime::getLastErrors() 方法 来检测所给定的日期时间字符串中是否包含格式字符串指定的内容之外的数据。

如果在格式字符串中包含不可识别的字符， 那么会导致解析失败，并且在返回的结构中附加一个错误信息。 可以通过 DateTime::getLastErrors() 来探查解析是否存在错误。

如果需要在格式字符串 format 参数中使用 上述表示格式的字符作为一个普通字符，请对其使用反斜线（\）进行转义。

如果格式字符串参数 format 中不包含 ! 字符， 那么没有在 format 参数中指明的字段， 在解析结果中将会被设置为系统当前时间对应的字段值。

如果格式字符串参数 format 包含了 ! 字符， 那么没有在 format 参数中指明的字段， 以及在 ! 左侧对应的字段， 在解析结果中将会被设置为 Unix epoch 时间对应的字段。

The Unix epoch 为 1970-01-01 00:00:00 UTC。

time

用来表示日期时间的字符串。

timezone

DateTimeZone 对象， 表示在解析日期时间字符串的时候需要使用的时区。

如果忽略 timezone 参数， 并且表示日期时间的字符串 time 中也不包含时区信息， 那么将会使用系统当前时区作为解析结果对象的时区。

注意:

如果 time 参数 是 UNIX 时间戳格式（例如：946684800）， 或者其中已经包含了时区信息（例如：2010-01-28T15:00:00+02:00）， 那么 timezone 以及系统当前时区 都将会被忽略。

返回值

返回一个 DateTime 对象。 或者在失败时返回 false。

更新日志

版本 说明
5.3.9 新增 format 格式字符串中对于 + 格式字符的支持。

范例

示例 #1 DateTime::createFromFormat() 例程

面向对象风格

<?php
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>

过程化风格

<?php
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
echo date_format($date, 'Y-m-d');
?>

以上例程会输出：

2009-02-15

示例 #2 DateTime::createFromFormat() 的复杂用法

<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTime::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>

以上例程的输出类似于：

Current time: 2010-04-23 10:29:35
Format: Y-m-d; 2009-02-15 10:29:35
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
Format: !d; 1970-01-15 00:00:00

示例 #3 格式化字符串中包含了需要进行转义的字符

<?php
echo DateTime::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
?>

以上例程的输出类似于：

23:15:03

参见