DateTime::createFromFormat

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7)

DateTime::createFromFormat -- date_create_from_format Разбирает строку, содержащую время, в соответствии с заданным форматом

Описание

Объектно-ориентированный стиль

public static DateTime DateTime::createFromFormat ( string $format , string $time [, DateTimeZone $timezone ] )

Процедурный стиль

DateTime date_create_from_format ( string $format , string $time [, DateTimeZone $timezone ] )

Создает и возвращает экземпляр класса DateTime, соответствующий заданному формату.

Список параметров

format

Формат даты и времени в виде строки (string), которому соответствует значение второго аргумента функции. Список вариантов форматирования представлен ниже. В большинстве случаев, при форматировании используются те же символы, что и в функции date().

Список возможных символов для составления строки format
Символ в строке format Описание Возможные значения
День --- ---
d и j День месяца, 2 цифры с нулем в начале или без него От 01 до 31 либо от 1 до 31
D и l Текстовое представление дня месяца От Mon до Sun либо от Sunday до Saturday
S Суффикс для числа в английской нумерации, 2 буквы. Эти буквы будут пропущены при разборе строки. st, nd, rd или th.
z Номер дня с начала года (начиная с нуля) C 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 и H 24-х часовой формат времени с нулем в начале или без него С 0 по 23 или с 00 по 23
i Минуты с нулем в начале С 00 по 59
s Секунды с нулем в начале От 00 до 59
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
Пробел и Разделители --- ---
(пробел) Один пробел или один отступ табуляции Пример:
# Один из следующих символов: ;, :, /, ., ,, -, ( или ) Пример: /
;, :, /, ., ,, -, ( или ) Символ разделитель. Пример: -
? Один случайный (любой) символ Пример: ^ (Будьте внимательны: в UTF-8 кодировке вам может потребоваться более одного ?, так как там один символ может занимать более одного байта. В таких случаях может помочь использование *.
* Любое количество любых символов до следующего разделителя Пример: * в Y-*-d для строки 2009-aWord-08 будет соответствовать aWord
! Приводит значения всех полей (год, месяц, день, час, минута, секунда, временная зона) ко времени начала Эпохи Unix. Без ! все поля будут соответствовать текущему времени.
| Приводит значения незаданных полей (год, месяц, день, час, минута, секунда, временная зона) ко времени начала Эпохи Unix. Y-m-d| установит год, месяц и день в соответствии с данными в строке, а часы, минуты и секунды установит в 0.
+ Если задан этот спецификатор, данные, завершающие строку (нуль байт например) не будут вызывать ошибку, только предупреждение Используйте DateTime::getLastErrors() для определения, были ли в строке завершающие символы.

Наличие в строке формата нераспознаваемых символов, отсутствующих в списке выше, приведет к ошибке разбора строки. В этом случае сообщение об ошибке будет добавлено в возвращаемую структуру. Получить это сообщение можно с помощью функции DateTime::getLastErrors().

Для вставки в format буквенного символа, вы должны экранировать его с помощью обратного слеша(\).

Если format не содержит символ !, то значения полей, не заданных в строке формата, будут установлены в соответствии с текущим временем.

Если format содержит символ !, то значения полей, не заданных в строке формата (равно как и значения полей слева от !) будут установлены в соответствии со значениями полей начала Эпохи Unix.

Начало эпохи Unix 1970-01-01 00:00:00 UTC.

time

Строка, представляющая время.

timezone

Объект класса DateTimeZone, представляющий ожидаемую временную зону.

Если timezone не указан и time не содержит временную зону, то будет использована текущая временная зона.

Замечание:

Параметр timezone и текущая временная зона будут проигнорированы, если параметр time также содержит метку времени UNIX (т.е. timestamp вида 946684800) или же указанную временную зону (т.е. 2010-01-28T15:00:00+02:00).

Возвращаемые значения

Возвращает созданный экземпляр класса 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 'Текущее время: ' date('Y-m-d H:i:s') . "\n";

$format 'Y-m-d';
$date DateTime::createFromFormat($format'2009-02-15');
echo 
"Формат: $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; " $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; " $date->format('Y-m-d H:i:s') . "\n";

$format '!d';
$date DateTime::createFromFormat($format'15');
echo 
"Формат: $format; " $date->format('Y-m-d H:i:s') . "\n";
?>

Результатом выполнения данного примера будет что-то подобное:

Текущее время: 2010-04-23 10:29:35
Формат: Y-m-d; 2009-02-15 10:29:35
Формат: Y-m-d H:i:s; 2009-02-15 15:16:17
Формат: Y-m-!d H:i:s; 1970-01-15 15:16:17
Формат: !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 add a note

User Contributed Notes 20 notes

up
83
falundir at gmail dot com
5 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
?>
up
34
Albie at aveit dot org
2 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
?>
up
32
d dot shankarnarayana at gmail dot com
3 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
up
10
lsloan-php dot net at umich dot edu
1 year 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"
up
8
tuxedobob
1 year 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
up
11
kamil dot wegrzynowicz at baobaz dot com
5 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)
up
2
vijaycs85 at gmail dot com
1 year 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
up
7
ELPI
3 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
?>
up
4
mail at marcel-juenemann dot de
4 years ago
Note that the U option does not support negative timestamps (before 1970). You have to use date for that.
up
3
joereynolds952 at gmail dot com
11 months 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.
up
4
SeliusX
2 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);
up
12
thomas dot ribiere at allgoob dot com
5 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");
?>
up
3
chernomyrdin at gmail dot com
2 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)
up
6
nicodoggie at gmail dot com
3 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"
}
up
3
klugg at tlen dot pl
6 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"

?>
up
1
jplevene
2 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.
up
1
Fabian
4 months 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.
up
1
thflori
10 months 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')));

?>
up
-1
Aurelien Marchand
6 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

?>
up
-3
rasmus at mindplay dot dk
1 year 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 :-*
To Top