PHP date_create_immutable() Function

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

Definition

In PHP, date_create_immutable() builds a new DateTimeImmutable object from a date and time string. If the string cannot be parsed, it returns false.

A DateTimeImmutable never changes after it is created. Methods like add(), sub() and modify() return a new object and leave the original untouched, which prevents many hard to find bugs. date_create_immutable() is the procedural form of new DateTimeImmutable(), but it returns false instead of throwing an exception.

Syntax

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

PHP
$date = date_create_immutable('2024-01-15 10:30:00');
CallWhat it does
date_create_immutable('2024-01-15')Returns an immutable object for midnight on January 15, 2024.
date_create_immutable('2024-01-15 +1 month')Understands relative text and returns February 15, 2024.
date_create_immutable('2024-01-15', new DateTimeZone('UTC'))Reads the string in the UTC timezone.

Use DateTimeImmutable when teaching or writing modern PHP. Remember to store the result of every change, for example $new = $date->modify('+1 day'). The old procedural helpers date_add(), date_sub() and date_date_set() only accept DateTime, but date_format() and date_diff() accept both.

Library declarations
PHP
date_create_immutable(string $datetime = "now", ?DateTimeZone $timezone = null): DateTimeImmutable|false

Parameters

ParameterDescription
datetimeOptional. A date and time string that PHP can parse. The default is "now", which is the current time.
timezoneOptional. A DateTimeZone object. It is ignored if the string has its own timezone or is a Unix timestamp such as '@1705314600'. If null, the default timezone is used.

Return Value

Return ValueDescription
DateTimeImmutableA new immutable date object when the string could be parsed.
falseReturned when the string cannot be parsed.

PHP Examples

Example 1 — Creating an Immutable Date

Create a DateTimeImmutable and change it with modify(). The original value stays the same and the change appears in a new object.

PHP
<?php
$a = date_create_immutable('2024-01-15 10:30:00');
echo get_class($a), PHP_EOL;
echo date_format($a, 'Y-m-d H:i'), PHP_EOL;

$b = $a->modify('+1 day');
echo date_format($a, 'Y-m-d'), PHP_EOL;
echo date_format($b, 'Y-m-d'), PHP_EOL;

How It Works

  1. date_create_immutable() returns a DateTimeImmutable object, not a plain DateTime.
  2. date_format() prints the date and time that were passed in.
  3. modify('+1 day') does not change $a. It returns a brand new object that is stored in $b.
  4. The original stays 2024-01-15 while the new object is 2024-01-16.

Example 2 — Immutable vs Mutable and Invalid Text

A DateTime changes in place, while a discarded DateTimeImmutable result changes nothing. Invalid text returns false.

PHP
<?php
var_dump(date_create_immutable('nonsense'));

$m = date_create('2024-01-15');
$m->modify('+1 month');
echo $m->format('Y-m-d'), PHP_EOL;

$i = date_create_immutable('2024-01-15');
$i->modify('+1 month');
echo $i->format('Y-m-d'), PHP_EOL;

How It Works

  1. 'nonsense' cannot be parsed, so date_create_immutable() returns false.
  2. A regular DateTime from date_create() is modified in place, so $m becomes 2024-02-15.
  3. For the immutable object, modify() returns a new object, but the result was thrown away.
  4. So $i is still 2024-01-15. This is the most common beginner mistake with immutables.

Example 3 — Safe Helper Functions

Immutable objects are safe to pass into functions. The function cannot change the caller's date by accident.

PHP
<?php
function addDays(DateTimeImmutable $d, int $n): DateTimeImmutable
{
    return $d->add(new DateInterval('P' . $n . 'D'));
}

$start = date_create_immutable('2024-01-15');
$later = addDays($start, 30);

echo date_format($start, 'Y-m-d'), PHP_EOL;
echo date_format($later, 'Y-m-d'), PHP_EOL;
echo date_format($later, 'D'), PHP_EOL;

How It Works

  1. addDays() accepts a DateTimeImmutable and builds an interval such as P30D.
  2. $d->add() returns a new object, so the original date is not touched.
  3. After the call, $start is still 2024-01-15 and $later is 2024-02-14.
  4. The D format prints the short weekday, and February 14, 2024 is a Wednesday.

Frequently Asked Questions

It creates a DateTimeImmutable object from a date string. The object cannot be changed after creation, and every change returns a new object.
date_create() returns a DateTime that is modified in place by methods such as add() and modify(). date_create_immutable() returns a DateTimeImmutable, where those methods return new objects and leave the original alone.
Because it returns a new object instead of changing the old one. Store the result in a variable, like $next = $date->modify('+1 day').
No. date_add() only accepts DateTime. Call $immutable->add($interval) instead. Functions such as date_format() and date_diff() accept both classes.
It returns false when the string cannot be parsed. new DateTimeImmutable() throws an exception instead, so pick the style that fits your error handling.

Next: date_create_immutable_from_format()

date_create_immutable_from_format() builds a DateTimeImmutable object from a date string t.

date_create_immutable_from_format() 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