Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Date and Time

The DateTime class

Reference for the PHP DateTime class: create, format, modify, compare and convert mutable date-time objects, with createFromFormat, time zones and the mutation trap.

DateTime represents a single moment together with a time zone. You can create one from text or from a format, print it with format(), move it with modify(), add() and sub(), and convert its zone with setTimezone().

DateTime is mutable: methods such as modify() and add() change the object itself and return $this. That is convenient in a small script, but it causes bugs when the same object is shared. For most new code, DateTimeImmutable is the safer choice and has an almost identical API; everything here applies to it unless noted.

PHP
<?php
$d = new DateTime("2025-03-01 09:30", new DateTimeZone("UTC"));
echo $d->format("D, d M Y H:i");   // Sat, 01 Mar 2025 09:30

Try it

PHP Create, format and modify

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 createFromFormat, comparison and the mutation trap

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 DateTime(string $datetime = "now", ?DateTimeZone $timezone = null)

DateTime::createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false
DateTime::createFromImmutable(DateTimeImmutable $object): DateTime
$dt->format(string $format): string
$dt->modify(string $modifier): DateTime|false
$dt->add(DateInterval $interval): DateTime
$dt->sub(DateInterval $interval): DateTime
$dt->setDate(int $year, int $month, int $day): DateTime
$dt->setTime(int $hour, int $minute, int $second = 0, int $microsecond = 0): DateTime
$dt->setTimestamp(int $timestamp): DateTime
$dt->setTimezone(DateTimeZone $timezone): DateTime
$dt->getTimestamp(): int
$dt->getTimezone(): DateTimeZone|false
$dt->getOffset(): int
$dt->diff(DateTimeInterface $target, bool $absolute = false): DateInterval
Name Description
$datetime Text understood by the same parser as strtotime(), or text matching $format.
$timezone Zone used to interpret text that has no zone of its own. If omitted, the default time zone is used.
$format A format string. Characters of createFromFormat() differ slightly from date(), for example ! and `
$modifier Relative text such as +1 week, next monday or first day of next month.

Return value: the constructor returns the object. Mutators return the same object. createFromFormat() returns false when the text does not match. format() returns a string.

Exceptions: the constructor throws DateMalformedStringException (a subclass of Exception, PHP 8.3 and later) for unparseable text, and DateInvalidTimeZoneException for a bad zone name. modify() throws in PHP 8.3 and later; before it emitted a warning and returned false.

Usage notes

  • Mutation surprises. $b = $a shares one object, and modify() changes both names. Use clone or DateTimeImmutable.
  • Month-end arithmetic. +1 month from 31 January lands on 3 March (or 2 March in leap years). Use last day of next month when you mean month ends.
  • Zones. The zone is part of the object. setTimezone() keeps the same instant and changes how it is displayed.
  • Comparison. <, > and == compare instants, so two objects in different zones can be equal.
  • createFromFormat() fills missing fields with the current time unless you put ! or | in the format. Read DateTime::getLastErrors() for the reason of a failure.
  • Daylight saving. +1 day keeps wall-clock time across a change, while +24 hours adds exact elapsed time. They can differ by an hour.
  • Type hints. Accept DateTimeInterface in your functions to allow both DateTime and DateTimeImmutable.
  • Formatting uses the same characters as date(), and microseconds (u) are real.