PHP-Funktion date_time_set()

In PHP wird die Methode DateTime::setTime() verwendet, um eine neue Uhrzeit für ein gegebenes DateTime-Objekt zu setzen. Diese Methode ist Teil der PHP-Klasse DateTime und kann genutzt werden, um den Zeitteil eines Datums-/Uhrzeitobjekts auf einen neuen Wert zu setzen.

Syntax

Die Syntax der Methode DateTime::setTime() lautet wie folgt:

Die Syntax der Methode DateTime::setTime()

$datetime->setTime($hour, $minute, $second, $microsecond);

Dabei gilt:

• $datetime ist das zu ändernde DateTime-Objekt.
• $hour ist der neue Stundenwert (0–23).
• $minute ist der neue Minutenwert (0–59).
• $second ist der neue Sekundenwert (0–59, optional, Standardwert ist 0).
• $microsecond ist der neue Mikrosekundenwert (0–999999, optional, Standardwert ist 0).

Hinweis: Die Zeitzone des DateTime-Objekts bleibt bei diesem Vorgang erhalten. Die Methode ändert das Objekt direkt. Wenn die angegebenen Werte ihre gültigen Bereiche überschreiten, normalisiert PHP sie automatisch (z. B. wird Stunde 25 auf den nächsten Tag verschoben), anstatt eine Ausnahme auszulösen.

Beispielverwendung

Sehen wir uns ein Beispiel an, wie die Methode DateTime::setTime() verwendet wird:

Beispiel der PHP-Methode DateTime::setTime()

In diesem Beispiel erstellen wir zunächst ein neues DateTime-Objekt mit dem Datum und der Uhrzeit '2000-01-01 12:00:00'. Anschließend verwenden wir die Methode setTime(), um die Stunde auf 14 und die Minute auf 30 zu setzen. Schließlich verwenden wir die Methode format(), um das geänderte Datum und die Uhrzeit im Format 'Y-m-d H:i:s' auszugeben. Das Ergebnis lautet:

2000-01-01 14:30:00

Da wir weder $second noch $microsecond übergeben haben, sind beide standardmäßig 0, sodass die Sekunden zurückgesetzt werden, obwohl die ursprüngliche Uhrzeit bereits :00 Sekunden hatte.

Sekunden und Mikrosekunden setzen

Sie können alle vier Argumente übergeben, um die Uhrzeit bis auf die Mikrosekunde genau zu steuern. Die Mikrosekundenkomponente erscheint nur in der Ausgabe, wenn Ihr Formatstring u enthält:

<?php
$date = new DateTime('2000-01-01 12:00:00');
$date->setTime(14, 30, 15, 500000);
echo $date->format('Y-m-d H:i:s.u');

Dies gibt 2000-01-01 14:30:15.500000 aus.

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

setTime() löst keine Ausnahme bei Werten außerhalb des gültigen Bereichs aus — es normalisiert sie und überträgt den Überlauf auf das Datum. Das Setzen der Stunde auf 25 verschiebt das Datum um einen Tag nach vorne:

<?php
$date = new DateTime('2000-01-01 23:30:00');
$date->setTime(25, 0);
echo $date->format('Y-m-d H:i:s');

Dies gibt 2000-01-02 01:00:00 aus — Stunde 25 wird zu 01:00 am nächsten Tag. Dies ist praktisch für Berechnungen (z. B. „5 Stunden addieren" durch Übergabe von $hour + 5), kann jedoch zu stillen Fehlern führen, wenn eine Validierung erwartet wurde. Um das Datum direkt zu ändern, verwenden Sie setDate() oder modify() für relative Verschiebungen.

Vergleich von DateTime::setTime() mit anderen Funktionen

Die Methode DateTime::setTime() ist der objektorientierte Standardansatz in PHP zur Änderung von Uhrzeiten. Im Gegensatz zu prozeduralen Datumsfunktionen, die neue Strings zurückgeben oder komplexes Parsen erfordern, ändert setTime() das DateTime-Objekt direkt, was Typsicherheit und konsistentes Verhalten gewährleistet.

Dies steht im Gegensatz zu DateTimeImmutable::setTime(), die eine neue Instanz zurückgibt und das Original unverändert lässt:

<?php
$original = new DateTimeImmutable('2000-01-01 12:00:00');
$changed  = $original->setTime(8, 0);

echo $original->format('H:i'), ' | ', $changed->format('H:i');

Dies gibt 12:00 | 08:00 aus: $original ist unverändert, und $changed enthält die neue Uhrzeit. Bei der veränderbaren Klasse DateTime gibt der Aufruf dasselbe geänderte Objekt zurück, sodass $original und $changed auf dasselbe 08:00-Objekt zeigen würden. Bevorzugen Sie DateTimeImmutable, wenn ein Wert geteilt oder weitergegeben wird, um unbeabsichtigte Mutationen zu vermeiden.

Verwandte Methoden, die Sie zusammen mit setTime() verwenden könnten: setDate() zum Ändern von Jahr/Monat/Tag, setTimezone() zum Konvertieren in eine andere Zeitzone und date_default_timezone_set() zum Festlegen der skriptweiten Standardzeitzone. Zum erstmaligen Erstellen des Objekts siehe new DateTime.

Fazit

Die Methode DateTime::setTime() ist ein nützliches Werkzeug zur Manipulation von Datum und Uhrzeit in PHP. Sie bietet eine unkomplizierte Möglichkeit, den Zeitteil eines DateTime-Objekts zu aktualisieren, und ermöglicht damit eine praktische und zuverlässige Vorgehensweise bei der Datums-/Uhrzeitbearbeitung. Für unveränderliche Datumsverarbeitung verwenden Sie DateTimeImmutable::setTime(), die eine neue Instanz zurückgibt, anstatt das Original zu ändern.

Übungen