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 $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
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 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 = $ashares one object, andmodify()changes both names. UsecloneorDateTimeImmutable. - Month-end arithmetic.
+1 monthfrom 31 January lands on 3 March (or 2 March in leap years). Uselast day of next monthwhen 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. ReadDateTime::getLastErrors()for the reason of a failure.- Daylight saving.
+1 daykeeps wall-clock time across a change, while+24 hoursadds exact elapsed time. They can differ by an hour. - Type hints. Accept
DateTimeInterfacein your functions to allow bothDateTimeandDateTimeImmutable. - Formatting uses the same characters as
date(), and microseconds (u) are real.