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 $datetime, DateTimeZone|null $timezone = null): DateTime|false

手続き型

date_create_from_format(string $format, string $datetime, DateTimeZone|null $timezone = null): DateTime|false

新しい DateTime オブジェクトを返します。このオブジェクトは、datetime で指定した文字列を format で指定した書式に沿って解釈した時刻を表します。

パラメータ

format

書式を文字列で渡します。以下の書式オプションを参照ください。大半は、date() で使える文字と同じです。

**`format` パラメータに渡せる文字**
`format` 文字	説明	取りうる値の例
日	---	---
`d` および `j`	2桁の日付。先頭のゼロを含むものと含まないもの	`01` から `31` あるいは `1` から `31`
`D` および `l`	曜日を表す文字列	`Mon` から `Sun` あるいは `Sunday` から `Saturday`
`S`	日付の後につける英語の接尾辞。二文字。処理中には無視されます。	`st`、`nd`、`rd` あるいは `th`
`z`	年始からの通算日数 (最初は 0)	`0` から `365`
月	---	---
`F` および `M`	月を表す文字列。January あるいは Sept など	`January` から `December` あるいは `Jan` から `Dec`
`m` および `n`	月を表す数値。先頭のゼロを含むものと含まないもの	`01` から `12` あるいは `1` から `12`
年	---	---
`Y`	4 桁の数値で表した年	例: `1999` あるいは `2003`
`y`	2 桁の数値で表した年 (1970年から2069年の間だとみなされます)	例: `99` あるいは `03` (それぞれ、 `1999` および `2003` と見なされます)
時刻	---	---
`a` および `A`	午前および午後	`am` あるいは `pm`
`g` および `h`	12 時間制での時間。先頭のゼロを含むものと含まないもの	`1` から `12` あるいは `01` から `12`
`G` and `H`	24 時間制での時間。先頭のゼロを含むものと含まないもの	`0` から `23` あるいは `00` から `23`
`i`	分。先頭のゼロを含む	`00` から `59`
`s`	秒。先頭のゼロを含む	`00` から `59`
`v`	ミリ秒。(最大 3桁)	例: `12`, `345`
`u`	マイクロ秒 (最大 6 桁)	例: `45`, `654321`
タイムゾーン	---	---
`e`、`O`、 `P` および `T`	タイムゾーン識別子、UTC からの時差 (時間単位)、 UTC からの時差 (コロン区切りでの時間と分)、そしてタイムゾーンの短縮形	例: `UTC`、`GMT`、 `Atlantic/Azores`、 `+0200`、`+02:00`、 `EST`、`MDT`
完全な日付/時刻	---	---
`U`	Unix エポック (January 1 1970 00:00:00 GMT) からの経過秒数	例: `1292177455`
空白および区切り	---	---
(空白)	空白 1 文字あるいはタブ 1 文字	例:
`#`	次の区切り文字のいずれか: `;`, `:`, `/`, `.`, `,`, `-`, `(`, `)`	例: `/`
`;`, `:`, `/`, `.`, `,`, `-`, `(`, `)`	指定した文字	例: `-`
`?`	ランダムなバイト	例: `^` (UTF-8 文字の場合は複数の `?` が必要になるでしょう。この場合、おそらく `*` を使うと要望が満たせるはずです)
`*`	次の区切り文字あるいは数字までのランダムなバイト列	例: `Y--d` の中の `` は、文字列 `2009-aWord-08` の中の `aWord` にマッチします
`!`	すべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする	`!` がなければ、すべてのフィールドは現在の日時に設定されます。
`\|`	まだパースされていないすべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする	`Y-m-d\|` は、文字列をパースした結果から年月日を設定し時分秒には 0 を設定します。
`+`	この文字があると、文字列のそれ以降のデータではエラーが発生せず、かわりに警告を発生させる	それ以降のデータが存在したかどうかを調べるには DateTime::getLastErrors() を使います。

書式文字列の中に解釈不能な文字が含まれていると処理は失敗し、返り値にはエラーメッセージが付加されます。エラーメッセージを調べるには DateTime::getLastErrors() を使います。

format にリテラル文字を含めるには、バックスラッシュ (\) でエスケープする必要があります。

format に文字 ! が含まれない場合は、作成した時刻値のうち format で指定されていない部分を現在のシステム時刻で初期化します。

format に文字 ! が含まれる場合は、作成した時刻値のうち format で指定されていない部分と ! の左側の部分を Unix エポックの対応する箇所の値で初期化します。

Unix エポックは 1970-01-01 00:00:00 です。

datetime

時刻を表す文字列。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

timezone を省略されるか、または null の場合、かつ datetime にタイムゾーンが含まれない場合は、現在のタイムゾーンを使います。

注意:
datetime パラメータが UNIX タイムスタンプ (例: 946684800) だったり、タイムゾーンを含んでいたり (例: 2010-01-28T15:00:00+02:00) する場合は、 timezone パラメータや現在のタイムゾーンは無視します。

返り値

新しい DateTime のインスタンス、失敗した場合に false を返します。

変更履歴

バージョン	説明
7.3.0	書式文字列 `v` が追加されました。

例

例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

参考

DateTime::__construct() - 新しい DateTime オブジェクトを返す
DateTime::getLastErrors() - 警告およびエラーを返す
checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
strptime() - strftime が生成した日付/時刻をパースする

add a note

User Contributed Notes 27 notes

down

122

falundir at gmail dot com ¶

11 years ago


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

down

Albie at aveit dot org ¶

8 years ago


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

down

d dot shankarnarayana at gmail dot com ¶

10 years ago


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

down

e dot fortmeyer01 at gmail dot com ¶

4 years ago


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

down

thflori ¶

7 years ago


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')));

?>

down

lsloan-php dot net at umich dot edu ¶

7 years ago


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"

down

tuxedobob ¶

8 years ago


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

down

Fabian ¶

6 years ago


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.

down

ELPI ¶

9 years ago


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

down

call4hemant at gmail dot com ¶

5 years ago


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

?>

down

labs at stronghold dot KILLIT dot media dot eu ¶

6 years ago


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.

down

c dot m dot tatro+php dot net at gmail dot com ¶

6 years ago


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

down

vijaycs85 at gmail dot com ¶

7 years ago


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

down

mail at marcel-juenemann dot de ¶

11 years ago


Note that the U option does not support negative timestamps (before 1970). You have to use date for that.

down

nicodoggie at gmail dot com ¶

9 years ago


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"
}

down

joereynolds952 at gmail dot com ¶

7 years ago


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.

down

Salman A ¶

6 years ago


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

down

SeliusX ¶

9 years ago


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);

down

thomas dot ribiere at allgoob dot com ¶

11 years ago


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");
?>

down

kamil dot wegrzynowicz at baobaz dot com ¶

12 years ago


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)

down

klugg at tlen dot pl ¶

13 years ago


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"

?>

down

chernomyrdin at gmail dot com ¶

8 years ago


<?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)

down

parmonov98 at yandex dot ru ¶

4 years ago


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.

down

mcab at acm dot org ¶

3 years ago


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".

down

jplevene ¶

8 years ago


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.

down

-2

Aurelien Marchand ¶

13 years ago


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

?>

down

-8

rasmus at mindplay dot dk ¶

7 years ago


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 :-*

add a note