PHP date_create_immutable_from_format() Function

The PHP date_create_immutable_from_format() function returns a new DateTimeImmutable object representing the date and time specified by the datetime string, which was formatted in the given format. This function is an alias of DateTimeImmutable::createFromFormat() method.

Syntax

//Object-oriented style
public DateTimeImmutable::createFromFormat(format, datetime, timezone)

//Procedural style
date_create_immutable_from_format(format, datetime, timezone)

Parameters

`format`	`Required.` Specify the format string to use. Refer to the table below for formatting options.
`datetime`	`Required.` Specify a date/time string.
`timezone`	`Optional.` Specify a DateTimeZone object representing the timezone of datetime. If omitted or null, the current timezone will be used. Default is the current timezone. Note: The parameter and the current timezone are ignored when the datetime parameter is either a UNIX timestamp or specifies a timezone (e.g. 2010-01-28T15:00:00+02:00).

format parameter string

Format character	Description	Example parsable values
Day
d	Day of the month, 2 digits with leading zeros	01 to 31
D	A textual representation of a day, three letters	Mon through Sun
j	Day of the month without leading zeros	1 to 31
l	A full textual representation of the day of the week	Sunday through Saturday
S	English ordinal suffix for the day of the month, 2 characters	st, nd, rd or th.
z	The day of the year (starting from 0)	0 through 365
Month
F	A full textual representation of a month, such as January or March	January through December
m	Numeric representation of a month, with leading zeros	01 through 12
M	A short textual representation of a month, three letters	Jan through Dec
n	Numeric representation of a month, without leading zeros	1 through 12
Year
Y	A full numeric representation of a year, 4 digits	Examples: 1999 or 2003
y	A two digit representation of a year	Examples: 99 or 03
Time
a	Lowercase Ante meridiem and Post meridiem	am or pm
A	Uppercase Ante meridiem and Post meridiem	AM or PM
g	12-hour format of an hour without leading zeros	1 through 12
G	24-hour format of an hour without leading zeros	0 through 23
h	12-hour format of an hour with leading zeros	01 through 12
H	24-hour format of an hour with leading zeros	00 through 23
i	Minutes with leading zeros	00 to 59
s	Seconds with leading zeros	00 through 59
u	Microseconds.	Example: 654321
v	Milliseconds. Same note applies as for u.	Example: 654
Timezone
e	Timezone identifier	Examples: UTC, GMT, Atlantic/Azores
O	Difference to Greenwich time (GMT) without colon between hours and minutes	Example: +0200
P	Difference to Greenwich time (GMT) with colon between hours and minutes	Example: +02:00
T	Timezone abbreviation, if known; otherwise the GMT offset.	Examples: EST, MDT, +05
Full Date/Time
U	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)	See time() function.
Whitespace and Separators
(space)	One space or one tab	Example:
#	One of the following separation symbol: ; : / . , - ( or )	Example: /
; : / . , - ( or )	The specified character.	Example: -
?	A random byte	Example: ^ (Be aware that for UTF-8 characters you might need more than one ?. In this case, using * is probably what you want instead)
*	Random bytes until the next separator or digit	Example: * in Y-*-d with the string 2009-aWord-08 will match aWord
!	Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to the Unix Epoch	Without !, all fields will be set to the current date and time.
\|	Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to the Unix Epoch if they have not been parsed yet	Y-m-d\| will set the year, month and day to the information found in the string to parse, and sets the hour, minute and second to 0.
+	If this format specifier is present, trailing data in the string will not cause an error, but a warning instead	Use DateTimeImmutable::getLastErrors() to find out whether trailing data was present.

Unrecognized characters in the format string will cause the parsing to fail and an error message is appended to the returned structure.

Return Value

Returns a new DateTimeImmutable instance or false on failure.

Example: using both styles

The example below shows the usage of date_create_immutable_from_format() function.

<?php
  //datetime string
  $datetime_string = "14-Dec-2015";
  
  //creating a DateTimeImmutable object from 
  //format using object-oriented style
  $date1 = DateTimeImmutable::createFromFormat("j-M-Y", $datetime_string);

  //creating a DateTimeImmutable object from 
  //format using procedural style
  $date2 = date_create_immutable_from_format("j-M-Y", $datetime_string);

  //formatting the datetime to print it
  echo date_format($date1, "d-M Y")."\n";
  echo date_format($date2, "d-M Y")."\n";
?>

The output of the above code will be:

14-Dec 2015
14-Dec 2015

Example: using different formats and timezone

Consider the example below where different formats and timezone are used to create a DateTimeImmutable object.

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

  $format_str = 'd-M-Y';
  $datetime_str = "15-Dec-2015";
  $date = date_create_immutable_from_format($format_str, $datetime_str);
  echo "Format ($format_str): ".date_format($date, 'Y-m-d H:i:s P')."\n";

  $format_str = 'd-M-Y H:i:s';
  $datetime_str = "15-Dec-2015 10:15:28";
  $date = date_create_immutable_from_format($format_str, $datetime_str);
  echo "Format ($format_str): ".date_format($date, 'Y-m-d H:i:s P')."\n";

  $format_str = 'd-M-Y H:i:s P';
  $datetime_str = "15-Dec-2015 10:15:28 +02:00";
  $date = date_create_immutable_from_format($format_str, $datetime_str);
  echo "Format ($format_str): ".date_format($date, 'Y-m-d H:i:s P')."\n";
?>

The output of the above code will be:

Current time: 2021-09-13 10:47:46 +00:00
Format (d-M-Y): 2015-12-15 10:47:46 +00:00
Format (d-M-Y H:i:s): 2015-12-15 10:15:28 +00:00
Format (d-M-Y H:i:s P): 2015-12-15 10:15:28 +02:00

❮ PHP Date and Time Reference