PHP-Funktion date_date_set()

In PHP setzen date_date_set() und sein objektorientiertes Pendant DateTime::setDate() ein neues Datum (Jahr, Monat und Tag) auf einem vorhandenen DateTime-object. Der Zeitteil des Objekts bleibt unverändert — nur das Kalenderdatum wird geändert. Dies ist das datumsseitige Gegenstück zu DateTime::setTime(), das nur die Uhrzeit ändert.

Verwenden Sie diese Funktion, wenn Sie bereits ein DateTime-object haben und es auf einen bestimmten Tag verschieben möchten, ohne das Objekt aus einem string neu aufzubauen.

Syntax

setDate() ist sowohl als Methode als auch als prozedurale Funktion verfügbar. Beide Formen tun genau dasselbe:

Die Syntax für DateTime::setDate() und date_date_set()

// Object-oriented style
$datetime->setDate($year, $month, $day);

// Procedural style
date_date_set($datetime, $year, $month, $day);

Dabei gilt:

• $datetime ist das zu ändernde DateTime-object.
• $year ist das neue Jahr (z. B. 2024).
• $month ist der neue Monat (1–12).
• $day ist der neue Tag des Monats (1–31).

Die Methode gibt dasselbe DateTime-object zurück, sodass Aufrufe verkettet werden können. Die vorhandene Uhrzeit, Mikrosekunden und Zeitzone des Objekts bleiben alle erhalten.

Verwendungsbeispiel

Setzen wir ein neues Datum auf einem DateTime-object, während wir seine ursprüngliche Uhrzeit beibehalten:

Beispiel der PHP DateTime::setDate()-Methode

Wir erstellen ein DateTime-object für 2000-01-01 12:30:00 und rufen dann setDate() auf, um das Datum auf den 15. Juli 2024 zu ändern. Da setDate() nur das Kalenderdatum berührt, bleibt die Uhrzeit 12:30:00 erhalten. Anschließend verwenden wir die format()-Methode, um das Ergebnis auszugeben:

2024-07-15 12:30:00

Prozedurale Schreibweise

Wenn Sie es bevorzugen (oder älteren Code lesen), kann dieselbe Änderung mit date_date_set() geschrieben werden. Es nimmt das object als erstes Argument:

<?php

$date = date_create('2000-01-01');
date_date_set($date, 2024, 7, 15);
echo $date->format('Y-m-d');

Dies gibt 2024-07-15 aus. Hier erstellt date_create() das object — es ist das prozedurale Äquivalent zu new DateTime.

Tage außerhalb des gültigen Bereichs werden übertragen

Wie der Rest der DateTime-API validiert setDate() den Tag nicht gegen die Länge des Monats. Stattdessen normalisiert es den Wert und überträgt jeden Überlauf in den nächsten Monat. Die Angabe von „31. Februar" ergibt ein Datum im März:

<?php

$date = new DateTime('2024-01-31');
$date->setDate(2024, 2, 31);
echo $date->format('Y-m-d');

Dies gibt 2024-03-02 aus: Der Februar 2024 hat 29 Tage, also liegt der 31. Tag 2 Tage nach dem Monatsende und fällt auf den 2. März. Dieses Übertragen ist praktisch für Datumsberechnungen, aber eine häufige Quelle stiller Fehler, wenn Sie eine Ausnahme erwartet haben. Um ein Datum um einen relativen Betrag zu verschieben, verwenden Sie stattdessen modify(), add() oder sub().

Veränderlich vs. unveränderlich

DateTime ist veränderlich (mutable): setDate() ändert das object an Ort und Stelle und gibt dasselbe object zurück. Wenn der Wert an anderer Stelle in Ihrem Code geteilt wird, sieht jede Referenz die Änderung. Um unbeabsichtigte Mutationen zu vermeiden, verwenden Sie DateTimeImmutable, dessen setDate() eine neue Instanz zurückgibt und das Original unberührt lässt:

<?php

$original = new DateTimeImmutable('2000-01-01');
$changed  = $original->setDate(2024, 7, 15);

echo $original->format('Y-m-d'), ' | ', $changed->format('Y-m-d');

Dies gibt 2000-01-01 | 2024-07-15 aus: $original ist unverändert, und $changed enthält das neue Datum. Bei dem veränderlichen DateTime würden beide Variablen auf dasselbe geänderte object zeigen.

Verwandte Methoden

setDate() wird selten allein verwendet. Sie werden es häufig kombinieren mit:

• setTime() — Stunde, Minute und Sekunde desselben Objekts ändern.
• setTimezone() — das object in eine andere Zeitzone konvertieren.
• date_default_timezone_set() — die skriptweite Standard-Zeitzone festlegen.
• new DateTime / date_create() — das object überhaupt erst erstellen.

Fazit

DateTime::setDate() (und das äquivalente date_date_set()) ist der saubere, objektorientierte Weg, Jahr, Monat und Tag eines DateTime-Objekts zu ändern und dabei seine Uhrzeit und Zeitzone zu bewahren. Merken Sie sich zwei Dinge: Tage außerhalb des gültigen Bereichs werden in den nächsten Monat übertragen, anstatt einen Fehler zu werfen, und das veränderliche DateTime wird an Ort und Stelle geändert — greifen Sie auf DateTimeImmutable zurück, wenn das Original unverändert bleiben soll.

Übungen