Datum und Zeit
**************

.[perex]
Nette bietet zwei Klassen für die Arbeit mit Datum und Zeit: [api:Nette\Utils\DateTimeImmutable] (unveränderlich, empfohlen) und [api: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":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes 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:

```shell
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:

```php
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.

```php
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 .[method]
-----------------------------------------------------------------------
Erzeugt ein Objekt aus einem String, einem UNIX-Timestamp oder einem anderen Objekt vom Typ [php:DateTimeInterface]. `null` bedeutet die aktuelle Zeit. Wirft eine Exception, wenn Datum und Zeit nicht gültig sind.

```php
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 .[method]
------------------------------------------------------------------------------------------------------------------
Erzeugt ein Objekt aus den einzelnen Bestandteilen oder wirft eine Exception, wenn Datum und Zeit nicht gültig sind.

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


static createFromFormat(string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false .[method]
---------------------------------------------------------------------------------------------------------------------------
Erweitert das native [php:DateTime::createFromFormat] um die Möglichkeit, die Zeitzone als String anzugeben.

```php
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()`.

```php
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:

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

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

```php
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.

```php
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:

```php
$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: .{data-version:4.0.7}

```php
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.