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 中的字符 解释 示例
--- ---
dj 一个月中的第几天,2 位数字表示,有前导 0 或者无前导 0 0131 或者 131
Dl 星期几的文字表示 MonSun 或者 SundaySaturday
S 2 个字母表示的一个月中的第几天(序数词), 在进行解析的时候会被忽略 stndrd 或者 th
z 一年中的第几天,从 0 开始 0365
--- ---
FM 文本表示的月份,例如 January 或者 Sept JanuaryDecember 或者 JanDec
mn 数值表示的月份,有前导 0 或者无前导 0 0112 or 112
--- ---
Y 4 位数字表示的年 例如:19992003
y 2 位数字表示的年, 可用的范围是 1970 至 2069(不含) 例如: 9903 (表示 19992003
时间 --- ---
aA 上午、下午 ampm
g and h 12 小时制的小时,有前导 0 或者无前导 0 112 或者 0112
GH 24 小时制的小时,有前导 0 或者无前导 0 0230023
i 分钟,有前导 0 0059
s 秒,有前导 0 0059
u 微秒,最多到 6 位数字 示例:45654321
时区 --- ---
eO, PT 时区名称,或者是以 UTC 时区为基准的小时偏移量, 或者是以 UTC 为基准的小时和分钟的偏移量, 小时和分钟之间用冒号(:)分隔。 示例:UTCGMTAtlantic/Azores+0200+02:00ESTMDT
完整的日期和时间 --- ---
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 中也不包含时区信息, 那么将会使用系统当前时区作为解析结果对象的时区。

Note:

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

返回值

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

更新日志

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

范例

Example #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

Example #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

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

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

以上例程的输出类似于:

23:15:03

参见

User Contributed Notes

mcab at acm dot org 11-May-2020 03:15
When using format "z Y" the function may return an incorrect date (as of 7.2.30).
I understand that this bug is being worked on but a simple solution that works now is to supply the year value first. i.e. always specify format "Y z".
parmonov98 at yandex dot ru 10-Mar-2020 11:16
sometimes we want unixtime rather than string date .
to get it from a string date,  do this.
$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
$date->format("U"); // will print unixtime.

I thought this would be helpful.
e dot fortmeyer01 at gmail dot com 01-Sep-2019 09:46
Be aware:
If the day of the month is not provided, creating a DateTime object will produce different results depending on what the current day of the year is.
This is because the current system date will be used where values are not provided.

<?php
function printMonth($month) {
    echo
DateTime::createFromFormat("F", "April")->format("F");
}

// on August 1st
printMonth("April");
// outputs April

// on August 31st
printMonth("April");
// outputs May
?>
call4hemant at gmail dot com 05-Sep-2018 09:02
<?php

// case 1: 13 as month will be converted to month=01 with Year=Year+1
$oDateTime1 = DateTime::createFromFormat( 'Y-m-d', '2018-13-10');
echo
$oDateTime1->format('Y-m-d');
// "2019-01-10" 

// case 2: 32 as date will convert date-01 and month=month+1
$oDateTime2= DateTime::createFromFormat( 'Y-m-d', '2018-12-32');
echo
$oDateTime2->format('Y-m-d');
// "2019-01-10"            

echo phpversion();
// 7.2.7-1+ubuntu16.04.1+deb.sury.org+12019-01-102019-01-01

?>
labs at stronghold dot KILLIT dot media dot eu 12-Apr-2018 04:36
Please note that several points here are wrong.
When using microseconds:

- The createFromFormat DOES NOT accept the ".v" modifier, unlike the formatting ones.

- When you provide microseconds to this function, YOU MUST LEFT PAD THEM to SIX digits with ZEROES.
If you don't, anything below 100000 will be RIGHT PADDED with zeroes.
(So that 999 becomes 9990000, while 1234 becomes 123400. (Also 0510 becomes 051000.)
But at least you can use milliseconds as microseconds. But then again, REMEMBER TO LEFT PAD them to 3 digits if necessary..

- WHAT?? Go provides SEVEN digits of MICROSECONDS?? Something there must definitely be wrong. Micro is, by definition, one millionth, so anything above 999999 is odd.
c dot m dot tatro+php dot net at gmail dot com 06-Apr-2018 05:49
Be aware that using this method when calling an invalid date still generates a date. For instance

DateTime::createFromFormat('Y F j', '2016 February 40');

generates a date like such: 2016-03-11
Salman A 05-Mar-2018 11:32
Seems like setting the hours to any value resets the remaining time portion (minute, second and milliseconds) to zero:

<?php
                                                            
// 2018-03-05 16:19:35.000000 <- now
DateTime::createFromFormat("Y-m-d",     "2000-01-01"      ); // 2000-01-01 16:19:35.000000
DateTime::createFromFormat("Y-m-d H",   "2000-01-01 00"   ); // 2000-01-01 00:00:00.000000
DateTime::createFromFormat("Y-m-d H",   "2000-01-01 01"   ); // 2000-01-01 01:00:00.000000
DateTime::createFromFormat("Y-m-d H:i", "2000-01-01 01:30"); // 2000-01-01 01:30:00.000000
?>

This is different from how missing year, month and dates are handled:

<?php
                                                            
// 2018-03-05 16:19:35.000000 <- now
DateTime::createFromFormat("Y-m H:i", "2000-01 01:30");      // 2000-01-05 01:30:00.000000
DateTime::createFromFormat("Y-d H:i", "2000-01 01:30");      // 2000-03-01 01:30:00.000000
?>
Fabian 25-Jul-2017 02:11
Parsing RFC3339 strings can be very tricky when their are microseconds in the date string.

Since PHP 7 there is the undocumented constant DateTime::RFC3339_EXTENDED (value: Y-m-d\TH:i:s.vP), which can be used to output an RFC3339 string with microseconds:

<?php
$d
= new DateTime();
var_dump($d->format(DateTime::RFC3339_EXTENDED)); // 2017-07-25T13:47:12.000+00:00
?>

But the same constant can't be used for parsing an RFC3339 string with microseconds, instead do:

<?php
$date
= DateTime::createFromFormat("Y-m-d\TH:i:s.uP", "2017-07-25T15:25:16.123456+02:00")
?>

But "u" can only parse microseconds up to 6 digits, but some language (like Go) return more than 6 digits for the microseconds, e.g.: "2017-07-25T15:50:42.456430712+02:00" (when turning time.Time to JSON with json.Marshal()). Currently there is no other solution than using a separate parsing library to get correct dates.

Note: the difference between "v" and "u" is just 3 digits vs. 6 digits.
thflori 30-Jan-2017 08:42
createFromFormat('U') has a strange behaviour: it ignores the datetimezone and the resulting DateTime object will always have GMT+0000 timezone.

<?php

$dt
= DateTime::createFromFormat('U', time(), new DateTimeZone('CET'));
var_dump($dt->format('Y-m-d H:i:s (T)'), date('Y-m-d H:i:s (T)', time()));

?>

The problem is microtime() and time() returning the timestamp in current timezone.  Instead of using time you can use 'now' but to get a DateTimeObject with microseconds you have to write it this way to be sure to get the correct datetime:

<?php

$dt
= \DateTime::createFromFormat('U.u', microtime(true))->setTimezone(new \DateTimeZone(date('T')));

?>
joereynolds952 at gmail dot com 17-Jan-2017 11:11
Just a note that it is possible to call createFromFormat non statically.

<?php
$today
= new DateTime();
$today->createFromFormat('Y-m-d', '2016-11-04'));
?>

Is perfectly valid.

We had to do this once we started using PHPMD which would complain about static methods.
vijaycs85 at gmail dot com 16-Dec-2016 12:31
There is no option to specify date format 'c' (e.g. 2004-02-12T15:19:21+00:00) directly. work around is to use Y-m-d\TH:i:sT
rasmus at mindplay dot dk 14-Oct-2016 12:50
Note a weird and surprising inconsistency in `DateTime::createFromFormat()` and `DateTimeImmutable::createFromFormat()` when the format is `"U"` and these factory-functions are called with a Unix timestamp - in this case, the timezone argument is not only ignored (as per the documentation) but also *NOT APPLIED* the constructed object!

In other words, the timezone argument has no effect in this case, at all, which I found pretty surprising. Of course the timezone argument cannot be used in this case to parse the value, since it's a timezone-neutral Unix timestamp, but I was definitely expecting the factory-function to apply the specified timezone to the created object - this is especially surprising when it comes to `DateTimeImmutable`, since this behavior of the factory-function makes it impossible to create an instance from a timestamp and initialize the timezone with a single call; you will need a subsequent call to `setTimezone()` discarding the original object.

Very strange and confusing design :-*
lsloan-php dot net at umich dot edu 20-May-2016 07:37
Reportedly, microtime() may return a timestamp number without a fractional part if the microseconds are exactly zero.  I.e., "1463772747" instead of the expected "1463772747.000000".  number_format() can create a correct string representation of the microsecond timestamp every time, which can be useful for creating DateTime objects when used with DateTime::createFromFormat():

<?php
$now
= DateTime::createFromFormat('U.u', number_format(microtime(true), 6, '.', ''));
var_dump($now->format('Y-m-d H:i:s.u')); // E.g., string(26) "2016-05-20 19:36:26.900794"
tuxedobob 21-Apr-2016 07:06
If you're here because you're trying to create a date from a week number, you want to be using setISODate, as I discovered here:

http://www.lornajane.net/posts/2011/getting-dates-from-week-numbers-in-php
Albie at aveit dot org 22-Nov-2015 06:58
If you want to safely compare equality of a DateTime object without explicitly providing the time portion make use of the ! format character.

<?php
$date1
= DateTime::createFromFormat('!Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('!Y-m-d', '2012-10-17');
/*
 $date1 and $date2 will both be set to a timestamp of "2012-10-17 00:00:00"
 var_dump($date1 == $date2); //will be true
 var_dump($date1 > $date2); //will be false
 var_dump($date1 < $date2); //will be false
*/
?>

If you omit the ! format character without explicitly providing the time portion your timestamp which will include the current system time in the stamp.

<?php
$date1
= DateTime::createFromFormat('Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date1 == $date2); //will be false
var_dump($date1 >= $date2); //will be false
var_dump($date1 < $date2); //will be true
?>
chernomyrdin at gmail dot com 19-Nov-2015 11:39
<?php
$date
= DateTime::createFromFormat('U.u', microtime(TRUE));
var_dump($date->format('Y-m-d H:i:s.u'));
?>
will print: 2015-11-19 11:37:29.125300 (the current time with microseconds)
jplevene 12-Jun-2015 03:09
To convert an email header date use the following (important, notice the * at the end)

$date = DateTime::createFromFormat('D, d M Y H:i:s O *', $email_date);

Some dates in email headers can be formatted as:
Fri, 12 Jun 2015 13:53:37 +0000 (UTC)

The "(UTC)" at the end of the date causes an error and will return a result of false unless the * is at the end.
SeliusX 30-Jan-2015 02:37
Creating timestamps to the day can result in hidden bugs cause hours are taken from now:

Example:
$newDateTime = DateTime::createFromFormat('Y-m-d', '2014-12-10');
$newDateTime->format('H') != '00';

Better use time too or erase the values later on:
$newDateTime = DateTime::createFromFormat('Y-m-d h:i', '2014-12-10 00:00');
or:
$newDateTime = DateTime::createFromFormat(''Y-m-d', '2014-12-10');
$newDateTime->setTime(0, 0);
ELPI 31-Oct-2014 10:04
It can be confusing creating new DateTime from timestamp when your default timezone (date.timezone) is different from UTC and you are used to date()-function.

date()-function automatically uses your current timezone setting but DateTime::createFromFormat (or DateTime constructor) does not (it ignores tz-parameter).

You can get same results as date() by setting the timezone after object creation.

<?php
$ts
= 1414706400;
$date1 = date("Y-m-d H:i", $ts);
$date2 = DateTime::createFromFormat("U", $ts)->setTimeZone(new DateTimeZone(date_default_timezone_get()))->format("Y-m-d H:i");
//$date1===$date2
?>
nicodoggie at gmail dot com 25-Jun-2014 01:20
I've found that on PHP 5.5.13 (not sure if it happens on other versions) if you enter a month larger than 12 on a format that takes numeric months, the result will be a DateTime object with its month equal to the number modulo 12 instead of returning false.

<?php
var_dump
(DateTime::createFromFormat('Y-m-d', '2013-22-01'));
?>

results in:
class DateTime#4 (3) {
  public $date =>
  string(19) "2014-10-01 13:05:05"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(3) "UTC"
}
d dot shankarnarayana at gmail dot com 24-Mar-2014 06:46
Say if there is a string with  $date = "today is 2014 January 1";   and you need to extract "2014 January" using DateTime::createFromFormat().  As you can see in the string there is something odd like "today is" .Since that string (today is) does not correspond to a date format, we need to escape that.

In this case, each and every character on that string has to be escaped as shown below.

The code.

<?php
$paragraph
= "today is 2014 January 1";
$date = DateTime::createFromFormat('\t\o\d\a\y \i\s Y F j', $paragraph);
echo
$date->format('Y F'); //"prints" 2014 January

- Shankar Damodaran
mail at marcel-juenemann dot de 17-Jan-2013 05:24
Note that the U option does not support negative timestamps (before 1970). You have to use date for that.
falundir at gmail dot com 17-Oct-2012 12:03
Be warned that DateTime object created without explicitely providing the time portion will have the current time set instead of 00:00:00.

<?php
$date
= DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date->format('Y-m-d H:i:s')); //will print 2012-10-17 13:57:34 (the current time)
?>

That's also why you can't safely compare equality of such DateTime objects:

<?php
$date1
= DateTime::createFromFormat('Y-m-d', '2012-10-17');
sleep(2);
$date2 = DateTime::createFromFormat('Y-m-d', '2012-10-17');
var_dump($date1 == $date2); //will be false
var_dump($date1 >= $date2); //will be false
var_dump($date1 < $date2); //will be true
?>
thomas dot ribiere at allgoob dot com 30-Aug-2012 03:46
Not a bug, but a strange issue today 2012-08-30 :

<?php
$date
= "2011-02";
echo
$date."\n";
$d = DateTime::createFromFormat("Y-m",$date);
echo
$d->format("Y-m");
?>
will display :
2011-02
2011-03

It's because there is no 2011-02-30, so datetime will take march insteed of february ...

To fix it :
<?php
$date
= "2011-02";
echo
$date."\n";
$d = DateTime::createFromFormat("Y-m-d",$date."-01");
echo
$d->format("Y-m");
?>
kamil dot wegrzynowicz at baobaz dot com 10-Feb-2012 08:05
It seems that a pipe ('|') option in formating string works only with PHP version 5.3.7 and newer. We had an issue with it on versions 5.3.2, 5.3.3, 5.3.6. Yet it was fine with 5.3.8 and 5.3.10.

By short example:
<?php
$timezone
= new DateTimeZone('UTC');
$dateTime = DateTime::createFromFormat('dmY|', '01011972', $timezone);
//$dateTime is FALSE in PHP v <5.3.8
?>

Instead we used a workaround:
<?php
$dateTime
= DateTime::createFromFormat('dmY', '01011972', $timezone);
$dateTime->format('Y-m-d 00:00:00');
?>
which works fine.

====

Modified by admin to correct for version (5.3.7 not 5.3.8)
Aurelien Marchand 29-Mar-2011 07:13
Beware specifying a timezone in the format as it will take precedence over the DateTimeZone object.

<?php
$timezone
= "UTC"; // or any other valid name for a timezone
$d= DateTime::createFromFormat("Y-m-d H:i:s T","2011-11-06 00:00:00 EDT",new DateTimeZone($timezone));
echo
$d->format("Y-m-d H:i:s T - U");
// returns "2011-11-06 00:00:00 EDT - 1320552000"
// specifying $timezone = "Pacific/Honolulu"; would return the same string
?>

This gets hairy when you are playing with transition from summer time to winter time! For instance, in Toronto, the time change happens on 2011-11-06. One second after 01:59:59 (EDT), the time becomes 01:00:00 (EST), or 1320559200 in Unix timestamp.

However, notice the following:
<?php
$d
= DateTime::createFromFormat("Y-m-d H:i:s","2011-11-06 01:00:00",new DateTimeZone("EST"));
echo
$d->format("Y-m-d H:i:s T U");
// returns "2011-11-06 01:00:00 EDT 1320555600" instead of "2011-11-06 01:00:00 EST 1320559200"

// so the correct way is to do:
$d = DateTime::createFromFormat("Y-m-d H:i:s T","2011-11-06 01:00:00 EST",new DateTimeZone($timezone)); // set $timezone to any valid string for DateTimeZone, it doesn't matter
echo $d->format("Y-m-d H:i:s T U");
// returns "2011-11-06 01:00:00 EST - 1320559200" as wanted

?>
klugg at tlen dot pl 14-Mar-2011 09:52
In order to use a DateTimeZone, don't enter one of the DateTimeZone::Europe, DateTimeZone::Asia etc. constants, but create a DateTimeZone object with verbal timezone name passed as a string:
<?php
$eventDate
= DateTime::createFromFormat('m/d/y h:i', '02/26/11 08:00', new DateTimeZone('Europe/Warsaw'));
echo
date_format($eventDate, 'Y-m-d'); //prints "2011-02-26"

?>