PHP date_create_immutable_from_format() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Date/Time

Definition

In PHP, date_create_immutable_from_format() builds a DateTimeImmutable object from a date string that follows a format you describe. If the string does not match the format, it returns false.

This is the immutable version of date_create_from_format() and the procedural alias of DateTimeImmutable::createFromFormat(). You tell PHP exactly how the text is laid out, which removes any guessing about day and month order. The returned object never changes, so it is a safe choice for modern PHP code.

Syntax

Call date_create_immutable_from_format() with the values you need. Start with this line.

PHP
$date = date_create_immutable_from_format('d/m/Y', '15/01/2024');
CallWhat it does
date_create_immutable_from_format('d/m/Y', '15/01/2024')Reads day, month and year from the string.
date_create_immutable_from_format('!d/m/Y', '15/01/2024')The ! resets the other fields, so the time is 00:00:00.
date_create_immutable_from_format('Y-m-d H:i', '2024-07-01 12:00', $tz)Reads the date and time in a given DateTimeZone.

This function is an alias of DateTimeImmutable::createFromFormat(). As with date_create_from_format(), any field missing from the format is filled with the current time, so start the format with ! when you only need a date.

Library declarations
PHP
date_create_immutable_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false

Parameters

ParameterDescription
formatRequired. The format of the input string, using the same letters as date(). Add ! at the start or | at the end to reset unparsed fields.
datetimeRequired. The string that must match the format exactly.
timezoneOptional. A DateTimeZone object. It is ignored when the string includes a timezone or the format uses U. If null, the default timezone is used.

Return Value

Return ValueDescription
DateTimeImmutableA new immutable object when the string matched the format.
falseReturned when the string does not match the format.

PHP Examples

Example 1 — Reading a Custom Format

Parse two different layouts into immutable objects, then print them in a new format.

PHP
<?php
$d = date_create_immutable_from_format('!d/m/Y', '15/01/2024');
echo get_class($d), PHP_EOL;
echo date_format($d, 'Y-m-d H:i:s'), PHP_EOL;

$e = date_create_immutable_from_format('Y-m-d H:i', '2024-03-05 18:45');
echo date_format($e, 'g:i A, M j'), PHP_EOL;

How It Works

  1. The format !d/m/Y says that the text is day, month and year, and that unparsed fields should be reset.
  2. Because of the !, the time is exactly 00:00:00.
  3. The second format reads a date and a time with hours and minutes.
  4. g:i A prints the 12 hour clock, giving 6:45 PM.

Example 2 — A Format Mismatch Returns false

If the text does not follow the format, the function returns false. Check for it before you use the result.

PHP
<?php
$bad = date_create_immutable_from_format('Y-m-d', '15/01/2024');
var_dump($bad);

if ($bad === false) {
    echo "Format did not match", PHP_EOL;
}

$ok = date_create_immutable_from_format('Y-m-d', '2024-01-15');
var_dump($ok instanceof DateTimeImmutable);

How It Works

  1. The format expects dashes, but the string uses slashes, so parsing fails.
  2. The function returns false instead of throwing an exception.
  3. Checking with === false lets your code handle the error politely.
  4. A string that matches the format returns a real DateTimeImmutable, which instanceof confirms.

Example 3 — Timezones Without Changing the Original

Create a date in London and convert it to UTC with setTimezone(). The original object keeps its own timezone.

PHP
<?php
$tz = new DateTimeZone('Europe/London');
$d = date_create_immutable_from_format('Y-m-d H:i', '2024-07-01 12:00', $tz);
echo date_format($d, 'c T'), PHP_EOL;

$utc = $d->setTimezone(new DateTimeZone('UTC'));
echo date_format($utc, 'c T'), PHP_EOL;
echo date_format($d, 'H:i'), PHP_EOL;

How It Works

  1. London uses British Summer Time in July, so the offset is +01:00 and the abbreviation is BST.
  2. setTimezone() on an immutable object returns a new object in the UTC timezone.
  3. The same moment shows as 11:00 in UTC, one hour earlier than London.
  4. The original $d is not changed and still prints 12:00.

Frequently Asked Questions

It reads a date string using a format you specify and returns a DateTimeImmutable object. If the string does not match the format, it returns false.
Yes. date_create_immutable_from_format() is the procedural alias of the static method DateTimeImmutable::createFromFormat(). They behave the same way.
date_create_from_format() returns a mutable DateTime, while this function returns a DateTimeImmutable. Everything else about the format letters and parsing is the same.
Any field not listed in the format is filled from the current moment. Put ! at the start of the format, or | at the end, to reset those fields to the epoch defaults.
The function returns false. You can call date_get_last_errors() to see warnings and error messages about the last parse.

Next: date_date_set()

date_date_set() changes the year, month and day of a DateTime object while keeping its tim.

date_date_set() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful