Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Date and Time

The DateTimeImmutable class

Reference for PHP DateTimeImmutable: the immutable date-time class whose methods return new objects, with chaining, createFromFormat, time zones and conversions.

DateTimeImmutable is the same idea as DateTime, a moment in time with a time zone, but its objects never change. Methods such as modify(), add(), setTime() and setTimezone() leave the original alone and return a new object.

That removes a whole class of bugs: you can pass a date to a function, store it in a value object or keep it as a constant without fearing that someone else mutates it. The cost is that you must use the return value. Both classes implement DateTimeInterface, so format(), getTimestamp(), diff() and comparisons work identically.

PHP
<?php
$a = new DateTimeImmutable("2025-03-01");
$b = $a->modify("+1 week");
echo $a->format("m/d"), " ", $b->format("m/d");   // 03/01 03/08

Try it

PHP Every change makes a new object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Parsing, converting and comparing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
new DateTimeImmutable(string $datetime = "now", ?DateTimeZone $timezone = null)

DateTimeImmutable::createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false
DateTimeImmutable::createFromMutable(DateTime $object): DateTimeImmutable
DateTimeImmutable::createFromInterface(DateTimeInterface $object): DateTimeImmutable
$dt->modify(string $modifier): DateTimeImmutable|false
$dt->add(DateInterval $interval): DateTimeImmutable
$dt->sub(DateInterval $interval): DateTimeImmutable
$dt->setDate(int $year, int $month, int $day): DateTimeImmutable
$dt->setTime(int $hour, int $minute, int $second = 0, int $microsecond = 0): DateTimeImmutable
$dt->setTimezone(DateTimeZone $timezone): DateTimeImmutable
$dt->format(string $format): string
$dt->diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval

The parameters match those of DateTime. Return value: every method that "changes" the date returns a new DateTimeImmutable; format() returns a string, getTimestamp() an int.

Exceptions: the constructor throws for text it cannot parse (DateMalformedStringException since PHP 8.3, Exception before), and DateInvalidTimeZoneException for unknown zone names. createFromFormat() returns false on a mismatch.

Usage notes

  • Use the return value. A bare $d->modify("+1 day"); does nothing useful, and PHP 8.5 emits a warning for it (the method is marked #[NoDiscard]). Assign the result.
  • Prefer it by default. Value objects, entities and function arguments are safer when dates cannot change underneath you.
  • Type against DateTimeInterface in parameters, and return DateTimeImmutable.
  • Convert at the edges: DateTimeImmutable::createFromMutable(), createFromInterface() and DateTime::createFromImmutable().
  • Comparison compares instants, so == is true for the same moment in different zones, and <=> works with usort().
  • Sub-day arithmetic such as +24 hours adds elapsed time, while +1 day keeps the local clock time across daylight saving changes.
  • Clones are cheap. There is no need to worry about the extra objects in normal code.
  • Doctrine, Carbon and Laravel all have immutable variants built on this class (CarbonImmutable).