date_modify()

This guide covers the PHP DateTime::modify() method (the object-oriented counterpart of the procedural date_modify() function). It explains how modify() parses relative date strings, what it returns, the month-overflow gotcha that trips up most developers, and how to avoid mutating a date by accident.

What is DateTime::modify()?

modify() is a built-in method of the DateTime class that alters the date/time it holds using a relative format string such as +10 days, -3 months, or next monday. Use it whenever you need date arithmetic — shifting a deadline forward, rolling a timestamp back, or jumping to the next weekday — without manually computing seconds.

Two things make modify() distinctive and are worth fixing in your mind before you read the examples:

• It mutates the object in place — it changes the same DateTime you call it on rather than returning a fresh copy.
• It accepts the same relative-format grammar PHP uses when constructing dates from strings, so anything new DateTime('+1 week') understands, modify() understands too.

Syntax

public DateTime::modify(string $modifier): DateTime|false

• $modifier — a relative-format string (e.g. +1 day, -2 weeks, first day of next month, 14:00).
• Returns the same DateTime object on success (so calls can be chained), or false on failure (for example, an unparsable string).

Because it returns the object itself, these two lines are equivalent — the original $date is modified either way:

$date->modify('+1 day');          // mutates $date, return value ignored
$date = $date->modify('+1 day');  // mutates $date AND reassigns the same object

Tip: When $modifier comes from user input, always check for false before using the result, since a malformed string returns false rather than throwing.

Examples

Example 1: Adding days to a date

To add 10 days to a fixed date with basic error handling:

Adding days to a date in PHP

Output:

2023-03-11

Example 2: Subtracting months from a date

To subtract 3 months from a fixed date:

Subtracting months from a date in PHP

Output:

2022-12-01

Example 3: Setting the time to a specific value

To set the time to 2 PM on a fixed date:

Setting the time to a specific value in PHP

Output:

2023-03-01 14:00:00

Note that modify('14:00') sets the time portion to 2 PM but leaves the date untouched — relative formats that mention only a time act on the time, not the day.

Example 4: Combining several units in one call

You can stack multiple relative units in a single modifier string, separated by spaces. They are applied left to right:

<?php

$date = new DateTime('2023-03-01');
$date->modify('+1 week +2 days');
echo $date->format('Y-m-d');

Output:

2023-03-10

The month-overflow gotcha

Adding or subtracting months does not clamp to the end of a shorter month — it overflows into the next one. Watch what happens when you add one month to January 31:

<?php

$date = new DateTime('2023-01-31');
$date->modify('+1 month');
echo $date->format('Y-m-d');

Output:

2023-03-03

Because February 2023 has only 28 days, "January 31 + 1 month" lands on the non-existent "February 31," which PHP rolls over to March 3. If you need the last day of next month instead, use an absolute relative format:

<?php

$date = new DateTime('2023-01-31');
$date->modify('last day of next month');
echo $date->format('Y-m-d');

Output:

2023-02-28

Avoid accidental mutation with DateTimeImmutable

Because modify() changes the object in place, sharing a single DateTime across your code can cause hard-to-find bugs — modifying it in one place affects every reference to it. If you want each operation to return a fresh value and leave the original intact, use DateTimeImmutable, whose modify() returns a new object:

<?php

$original = new DateTimeImmutable('2023-03-01');
$nextWeek = $original->modify('+7 days');

echo $original->format('Y-m-d') . "\n"; // unchanged
echo $nextWeek->format('Y-m-d');

Output:

2023-03-01
2023-03-08

Useful relative formats

modify() accepts a rich grammar of relative phrases. A few common ones:

Related functions

• date_add() — add a DateInterval to a date.
• date_sub() — subtract a DateInterval from a date.
• date_diff() — get the difference between two dates.
• date_format() — format a DateTime object as a string.

Summary

DateTime::modify() applies a relative-format string to a date, mutating the object in place and returning it (or false on failure). It is ideal for date arithmetic and jumping to named days, but remember two things: month math overflows past short months, and the mutation is shared — reach for DateTimeImmutable when you need the original preserved.

Practice