Datum und Zeit

Nette bietet zwei Klassen für die Arbeit mit Datum und Zeit: Nette\Utils\DateTimeImmutable (unveränderlich, empfohlen) und Nette\Utils\DateTime (veränderlich). Beide erweitern die nativen PHP-Klassen, sodass jede native Methode weiterhin zur Verfügung steht, und ergänzen dieselben zwei Verbesserungen.

Erstens sind sie streng. Während PHP ungültige Datumsangaben wie 0000-00-00 (das wird zu -0001-11-30) oder 2024-02-31 (das wird zu 2024-03-02) stillschweigend akzeptiert, werfen diese Klassen stattdessen eine Exception.

Zweitens korrigieren sie das Verhalten bei der Umstellung auf die Sommerzeit (DST), bei der im nativen PHP das Addieren einer relativen Zeit (etwa +100 minutes) zu einer früheren Zeit führen kann als das Addieren einer kürzeren Spanne (etwa +50 minutes). Diese Klassen sorgen dafür, dass die Arithmetik intuitiv funktioniert und +100 minutes immer mehr ist als +50 minutes.

Installation:

composer require nette/utils

Unveränderlich oder veränderlich?

Die Klasse DateTimeImmutable gibt es seit Version 4.1.5 und sie ist die empfohlene Wahl. Jede verändernde Methode gibt eine neue Instanz zurück, statt das Original zu ändern, ein Objekt, das Sie gespeichert oder an eine Funktion übergeben haben, kann sich also nie unerwartet ändern:

use Nette\Utils\DateTimeImmutable;

$date = new DateTimeImmutable('2024-02-26');
$next = $date->modify('+1 day');
echo $date; // 2024-02-26 00:00:00  (unverändert)
echo $next; // 2024-02-27 00:00:00  (ein neues Objekt)

DateTime ist veränderlich: Derselbe Aufruf ändert das Objekt an Ort und Stelle. Sie ist nicht veraltet, für neuen Code ist die unveränderliche Variante aber vorzuziehen.

use Nette\Utils\DateTime;

$date = new DateTime('2024-02-26');
$date->modify('+1 day');
echo $date; // 2024-02-27 00:00:00  (das Original hat sich geändert)

Weil beide Klassen die nativen erweitern, verwenden Sie weiterhin die Methoden, die Sie bereits kennen – format(), getTimestamp(), add(), sub(), diff(), setTimezone(), die Vergleichsoperatoren und so weiter. Bei DateTimeImmutable geben alle verändernden Methoden eine neue Instanz zurück. Der Rest dieser Seite beschreibt nur, was Nette darüber hinaus ergänzt; sofern nicht anders vermerkt, funktioniert alles bei beiden Klassen gleich.

Objekte erzeugen

static from (string|int|\DateTimeInterface|null $time): static

Erzeugt ein Objekt aus einem String, einem UNIX-Timestamp oder einem anderen Objekt vom Typ DateTimeInterface. null bedeutet die aktuelle Zeit. Wirft eine Exception, wenn Datum und Zeit nicht gültig sind.

DateTimeImmutable::from(1_138_013_640); // aus einem UNIX-Timestamp, mit der Standard-Zeitzone
DateTimeImmutable::from('1994-02-26 04:15:32'); // aus einem String
DateTimeImmutable::from('1994-02-26'); // aus einem Datum, die Zeit ist 00:00:00
DateTimeImmutable::from(null); // das aktuelle Datum samt Zeit

static fromParts (int $year, int $month, int $day, int $hour=0, int $minute=0, float $second=0.0): static

Erzeugt ein Objekt aus den einzelnen Bestandteilen oder wirft eine Exception, wenn Datum und Zeit nicht gültig sind.

DateTimeImmutable::fromParts(1994, 2, 26, 4, 15, 32);

static createFromFormat (string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false

Erweitert das native DateTime::createFromFormat um die Möglichkeit, die Zeitzone als String anzugeben.

DateTimeImmutable::createFromFormat('d.m.Y', '26.02.1994', 'Europe/London');

Strenge Validierung

Ein ungültiges Datum oder eine ungültige Zeit wird nie stillschweigend zurechtgebogen, sondern wirft immer eine Exception. Das gilt für jeden Weg, ein Objekt zu erzeugen oder zu ändern – den Konstruktor, from(), fromParts() sowie die Methoden setDate() und setTime().

new DateTimeImmutable('2024-02-31');         // wirft (der Februar hat keinen 31.)
DateTimeImmutable::fromParts(2024, 2, 31);   // wirft
$date->setDate(2024, 2, 31);                 // wirft
$date->setTime(25, 0);                       // wirft (es gibt keine 25. Stunde)

Ausgabe als String und JSON

__toString() gibt Datum und Zeit im Format Y-m-d H:i:s zurück, ein Objekt lässt sich also direkt ausgeben oder verketten:

echo $date; // '2017-02-03 04:15:32'

Beide Klassen implementieren JsonSerializable und serialisieren in das Format ISO 8601, das in JavaScript üblich ist:

echo json_encode($date); // '"2017-02-03T04:15:32+01:00"'

Zusätzliche Fähigkeiten von DateTime

Das veränderliche DateTime trägt einige zusätzliche Mitglieder, die nur bei einem veränderlichen Objekt Sinn ergeben und deshalb nicht Teil von DateTimeImmutable sind.

Seine Methode from() behandelt eine kleine Zahl außerdem als Versatz in Sekunden gegenüber der aktuellen Zeit. Die unveränderliche Variante lässt diese Abkürzung bewusst weg – dort ist eine Zahl immer ein wörtlicher Timestamp.

DateTime::from(42); // die aktuelle Zeit plus 42 Sekunden

modifyClone(string $modify=''): static gibt eine veränderte Kopie zurück und lässt das Original unangetastet. Bei einem veränderlichen Objekt bietet die Methode das, was modify() beim unveränderlichen von Haus aus liefert:

$original = DateTime::from('2017-02-03');
$clone = $original->modifyClone('+1 day');
$original->format('Y-m-d'); // '2017-02-03'  (unverändert)
$clone->format('Y-m-d');    // '2017-02-04'

DateTime::relativeToSeconds(string $relativeTime): int wandelt einen String mit einer relativen Zeit in Sekunden um:

DateTime::relativeToSeconds('1 minute'); // 60
DateTime::relativeToSeconds('-1 hour'); // -3600

Schließlich definiert DateTime die Konstanten MINUTE, HOUR, DAY, WEEK, MONTH und YEAR, die eine Länge in Sekunden ausdrücken; MONTH und YEAR sind Durchschnittswerte, verwenden Sie sie also nur für grobe Schätzungen.