date_modify()

Dieser Leitfaden behandelt die PHP-Methode DateTime::modify() (das objektorientierte Pendant zur prozeduralen Funktion date_modify()). Er erklärt, wie modify() relative Datumsstrings verarbeitet, was zurückgegeben wird, den Monatsüberlauf-Fallstrick, über den die meisten Entwickler stolpern, und wie unbeabsichtigte Mutationen eines Datums vermieden werden können.

Was ist DateTime::modify()?

modify() ist eine eingebaute Methode der DateTime-Klasse, die das gespeicherte Datum/die gespeicherte Zeit mithilfe eines relativen Formatstrings wie +10 days, -3 months oder next monday verändert. Verwende sie immer dann, wenn du Datumsarithmetik benötigst — eine Frist nach vorne verschieben, einen Zeitstempel zurückrollen oder zum nächsten Wochentag springen — ohne Sekunden manuell berechnen zu müssen.

Zwei Eigenschaften machen modify() besonders und sind es wert, sie zu verinnerlichen, bevor du die Beispiele liest:

• Sie mutiert das Objekt direkt — sie verändert dasselbe DateTime-Objekt, auf dem sie aufgerufen wird, anstatt eine neue Kopie zurückzugeben.
• Sie akzeptiert dieselbe Grammatik für relative Formate, die PHP beim Erstellen von Datumsangaben aus Strings verwendet. Alles, was new DateTime('+1 week') versteht, versteht auch modify().

Syntax

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

• $modifier — ein relativer Formatstring (z. B. +1 day, -2 weeks, first day of next month, 14:00).
• Rückgabewert: Bei Erfolg dasselbe DateTime-Objekt (Aufrufe können daher verkettet werden), oder false bei Fehler (z. B. bei einem nicht parsbaren string).

Da die Methode das Objekt selbst zurückgibt, sind diese zwei Zeilen gleichwertig — das ursprüngliche $date wird in beiden Fällen verändert:

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

Tipp: Wenn $modifier aus Benutzereingaben stammt, prüfe vor der Verwendung des Ergebnisses immer auf false, da ein fehlerhafter string false zurückgibt, anstatt eine Ausnahme auszulösen.

Beispiele

Beispiel 1: Tage zu einem Datum addieren

So werden mit einfacher Fehlerbehandlung 10 Tage zu einem festen Datum addiert:

Tage zu einem Datum in PHP addieren

Ausgabe:

2023-03-11

Beispiel 2: Monate von einem Datum subtrahieren

So werden 3 Monate von einem festen Datum subtrahiert:

Monate von einem Datum in PHP subtrahieren

Ausgabe:

2022-12-01

Beispiel 3: Die Uhrzeit auf einen bestimmten Wert setzen

So wird die Uhrzeit bei einem festen Datum auf 14:00 Uhr gesetzt:

Die Uhrzeit auf einen bestimmten Wert in PHP setzen

Ausgabe:

2023-03-01 14:00:00

Beachte, dass modify('14:00') den Zeitanteil auf 14:00 Uhr setzt, das Datum aber unverändert lässt — relative Formate, die nur eine Uhrzeit angeben, wirken auf die Zeit, nicht auf den Tag.

Beispiel 4: Mehrere Einheiten in einem Aufruf kombinieren

Du kannst mehrere relative Einheiten in einem einzigen Modifier-string kombinieren, getrennt durch Leerzeichen. Sie werden von links nach rechts angewendet:

<?php

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

Ausgabe:

2023-03-10

Der Monatsüberlauf-Fallstrick

Das Addieren oder Subtrahieren von Monaten begrenzt das Ergebnis nicht auf das Ende eines kürzeren Monats — es läuft in den nächsten Monat über. Schau, was passiert, wenn du einen Monat zum 31. Januar addierst:

<?php

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

Ausgabe:

2023-03-03

Da der Februar 2023 nur 28 Tage hat, landet „31. Januar + 1 Monat" auf dem nicht existierenden „31. Februar", den PHP auf den 3. März verschiebt. Wenn du stattdessen den letzten Tag des nächsten Monats benötigst, verwende ein absolutes relatives Format:

<?php

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

Ausgabe:

2023-02-28

Unbeabsichtigte Mutation mit DateTimeImmutable vermeiden

Da modify() das Objekt direkt verändert, kann das gemeinsame Verwenden eines einzelnen DateTime-Objekts im Code schwer zu findende Fehler verursachen — eine Änderung an einer Stelle betrifft alle Verweise darauf. Wenn jede Operation einen frischen Wert zurückgeben und das Original unverändert lassen soll, verwende DateTimeImmutable, dessen modify() ein neues Objekt zurückgibt:

<?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');

Ausgabe:

2023-03-01
2023-03-08

Nützliche relative Formate

modify() akzeptiert eine reichhaltige Grammatik an relativen Ausdrücken. Einige gebräuchliche Beispiele:

Verwandte Funktionen

• date_add() — ein DateInterval zu einem Datum addieren.
• date_sub() — ein DateInterval von einem Datum subtrahieren.
• date_diff() — die Differenz zwischen zwei Datumsangaben berechnen.
• date_format() — ein DateTime-Objekt als string formatieren.

Zusammenfassung

DateTime::modify() wendet einen relativen Formatstring auf ein Datum an, mutiert das Objekt direkt und gibt es zurück (oder false bei Fehler). Es ist ideal für Datumsarithmetik und das Springen zu benannten Tagen — aber merke dir zwei Dinge: Monatsrechnung überläuft bei kurzen Monaten, und die Mutation ist geteilt — greife auf DateTimeImmutable zurück, wenn das Original erhalten bleiben soll.

Übung