PHP Function Reference

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 characterDescriptionExample parsable values
Day
dDay of the month, 2 digits with leading zeros01 to 31
DA textual representation of a day, three lettersMon through Sun
jDay of the month without leading zeros1 to 31
lA full textual representation of the day of the weekSunday through Saturday
SEnglish ordinal suffix for the day of the month, 2 charactersst, nd, rd or th.
zThe day of the year (starting from 0)0 through 365
Month
FA full textual representation of a month, such as January or MarchJanuary through December
mNumeric representation of a month, with leading zeros01 through 12
MA short textual representation of a month, three lettersJan through Dec
nNumeric representation of a month, without leading zeros1 through 12
Year
YA full numeric representation of a year, 4 digitsExamples: 1999 or 2003
yA two digit representation of a yearExamples: 99 or 03
Time
aLowercase Ante meridiem and Post meridiemam or pm
AUppercase Ante meridiem and Post meridiemAM or PM
g12-hour format of an hour without leading zeros1 through 12
G24-hour format of an hour without leading zeros0 through 23
h12-hour format of an hour with leading zeros01 through 12
H24-hour format of an hour with leading zeros00 through 23
iMinutes with leading zeros00 to 59
sSeconds with leading zeros00 through 59
uMicroseconds.Example: 654321
vMilliseconds. Same note applies as for u.Example: 654
Timezone
eTimezone identifierExamples: UTC, GMT, Atlantic/Azores
ODifference to Greenwich time (GMT) without colon between hours and minutesExample: +0200
PDifference to Greenwich time (GMT) with colon between hours and minutesExample: +02:00
TTimezone abbreviation, if known; otherwise the GMT offset.Examples: EST, MDT, +05
Full Date/Time
USeconds since the Unix Epoch (January 1 1970 00:00:00 GMT)See time() function.
Whitespace and Separators
(space)One space or one tabExample:
#One of the following separation symbol: ; : / . , - ( or )Example: /
; : / . , - ( or ) The specified character.Example: -
?A random byteExample: ^ (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 digitExample: * 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 EpochWithout !, 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 yetY-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 insteadUse 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