Signatur
Beschreibung
date_time_set() ist die prozedurale Variante der Methode DateTime::setTime() und ermöglicht es, die Uhrzeit eines bestehenden DateTime-Objekts zu überschreiben, ohne das Datum zu verändern. Die Funktion gibt das modifizierte Objekt zurück, was Methoden-Verkettung in prozeduralem Stil unterstützt.
Typische Einsatzbereiche sind das Normalisieren von Datumswerten auf einen bestimmten Tageszeitpunkt (z. B. Mitternacht), das Zusammensetzen von Datum und Uhrzeit aus unterschiedlichen Quellen sowie die Vorbereitung von Zeitstempeln für Datenbankabfragen oder Berechnungen.
Werte außerhalb der normalen Grenzen werden automatisch übertragen: Ein $hour-Wert von 25 erhöht beispielsweise das Datum um einen Tag. Dieses Überlauf-Verhalten ist nützlich für arithmetische Zeitoperationen, kann aber bei unerwarteten Eingaben zu Überraschungen führen.
Für unveränderliche Datumsobjekte steht die Klasse DateTimeImmutable zur Verfügung, deren prozedurale Entsprechung date_time_set() hingegen nicht direkt unterstützt – dort sollte DateTimeImmutable::setTime() verwendet werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $object Pflicht | DateTime | Ein DateTime-Objekt, dessen Uhrzeit geändert werden soll. Das Objekt wird direkt modifiziert. |
|
| $hour Pflicht | int | Die Stunden (0–23). Werte außerhalb dieses Bereichs werden auf den nächsten Tag oder vorherigen Tag übertragen. | |
| $minute Pflicht | int | Die Minuten (0–59). Überlaufwerte werden entsprechend auf die Stunden übertragen. | |
| $second | int | 0 | Die Sekunden (0–59). Standardmäßig 0, wenn nicht angegeben. |
| $microsecond | int | 0 | Die Mikrosekunden (0–999999). Seit PHP 7.1.0 unterstützt. Standardmäßig 0. |
Rückgabewert
DateTime-Objekt zurück. Da das Objekt direkt verändert wird, ist der Rückgabewert identisch mit dem übergebenen Objekt und kann für Verkettung genutzt werden.Beispiele
Uhrzeit eines Datumsobjekts auf Mitternacht setzen
<?php
$date = date_create('2024-06-15 14:30:00');
date_time_set($date, 0, 0, 0);
echo date_format($date, 'Y-m-d H:i:s');
// Gibt das gleiche Datum, aber mit Uhrzeit 00:00:00 ausDatum und Uhrzeit aus separaten Quellen zusammenführen
<?php
// Datum aus einem Formular, Uhrzeit aus einer anderen Quelle
$datePart = date_create('2024-12-24');
date_time_set($datePart, 18, 30, 0);
echo date_format($datePart, 'd.m.Y H:i:s');
// Weihnachtsabend um 18:30 UhrÜberlaufverhalten bei Stundenwert > 23
<?php
$date = date_create('2024-01-01');
date_time_set($date, 25, 0, 0); // 25 Stunden = nächster Tag + 1 Stunde
echo date_format($date, 'Y-m-d H:i:s');// Wichtig · Fallstricke
Mikrosekunden (seit PHP 7.1.0): Der Parameter $microsecond wurde erst ab PHP 7.1.0 eingeführt. Bei älteren PHP-Versionen wird dieser Parameter ignoriert oder verursacht Fehler.
Objekt-Mutation: Im Gegensatz zu DateTimeImmutable wird das übergebene DateTime-Objekt direkt verändert. Wenn das ursprüngliche Objekt erhalten bleiben soll, muss vorher eine Kopie mit clone erstellt werden.
Überlaufwerte: PHP akzeptiert Werte außerhalb der normalen Grenzen und überträgt sie automatisch. Dies kann bei unkontrollierten Benutzereingaben zu unerwarteten Datumswerten führen. Eingaben sollten daher vor der Verwendung validiert werden.