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 $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
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.
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
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
DateTimeInterfacein parameters, and returnDateTimeImmutable. - Convert at the edges:
DateTimeImmutable::createFromMutable(),createFromInterface()andDateTime::createFromImmutable(). - Comparison compares instants, so
==is true for the same moment in different zones, and<=>works withusort(). - Sub-day arithmetic such as
+24 hoursadds elapsed time, while+1 daykeeps 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).