Data i czas
***********

.[perex]
Nette oferuje dwie klasy do pracy z datą i czasem: [api:Nette\Utils\DateTimeImmutable] (niezmienną, zalecaną) i [api:Nette\Utils\DateTime] (zmienną). Obie rozszerzają natywne klasy PHP, więc każda natywna metoda pozostaje dostępna, i dodają te same dwa usprawnienia.

Po pierwsze, są **rygorystyczne**. Podczas gdy PHP po cichu akceptuje nieprawidłowe daty, takie jak `0000-00-00` (zamienia na `-0001-11-30`) czy `2024-02-31` (zamienia na `2024-03-02`), te klasy zamiast tego zgłaszają wyjątek.

Po drugie, **naprawiają zachowanie** przy zmianach czasu letniego (DST), gdzie w natywnym PHP dodanie czasu względnego (np. `+100 minutes`) może "dać wcześniejszy czas":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes niż dodanie krótszego okresu (np. `+50 minutes`). Te klasy zapewniają, że arytmetyka działa intuicyjnie i `+100 minutes` jest zawsze więcej niż `+50 minutes`.

Instalacja:

```shell
composer require nette/utils
```


Niezmienna czy zmienna?
=======================

Klasa `DateTimeImmutable` jest dostępna od wersji 4.1.5 i jest zalecanym wyborem. Każda metoda modyfikująca zwraca **nową instancję**, zamiast zmieniać oryginał, więc obiekt, który gdzieś przechowujesz albo przekazałeś do funkcji, nigdy nie zmieni się nieoczekiwanie:

```php
use Nette\Utils\DateTimeImmutable;

$date = new DateTimeImmutable('2024-02-26');
$next = $date->modify('+1 day');
echo $date; // 2024-02-26 00:00:00  (bez zmian)
echo $next; // 2024-02-27 00:00:00  (nowy obiekt)
```

`DateTime` jest zmienna: to samo wywołanie zmienia obiekt w miejscu. Nie jest przestarzała, ale w nowym kodzie preferowany jest wariant niezmienny.

```php
use Nette\Utils\DateTime;

$date = new DateTime('2024-02-26');
$date->modify('+1 day');
echo $date; // 2024-02-27 00:00:00  (oryginał się zmienił)
```

Ponieważ obie klasy rozszerzają natywne, nadal używasz metod, które już znasz: `format()`, `getTimestamp()`, `add()`, `sub()`, `diff()`, `setTimezone()`, operatorów porównania itd. Na `DateTimeImmutable` wszystkie metody modyfikujące zwracają nową instancję. Reszta tej strony opisuje tylko to, co Nette dodaje ponad to; o ile nie zaznaczono inaczej, wszystko działa tak samo w obu klasach.


Tworzenie obiektów
==================


static from(string|int|\DateTimeInterface|null $time): static .[method]
-----------------------------------------------------------------------
Tworzy obiekt ze stringa, uniksowego timestampu albo innego obiektu [php:DateTimeInterface]. `null` oznacza bieżący czas. Zgłasza wyjątek, jeśli data i czas nie są prawidłowe.

```php
DateTimeImmutable::from(1_138_013_640); // z uniksowego timestampu, w domyślnej strefie czasowej
DateTimeImmutable::from('1994-02-26 04:15:32'); // ze stringa
DateTimeImmutable::from('1994-02-26'); // z daty, czas będzie 00:00:00
DateTimeImmutable::from(null); // bieżąca data i czas
```


static fromParts(int $year, int $month, int $day, int $hour=0, int $minute=0, float $second=0.0): static .[method]
------------------------------------------------------------------------------------------------------------------
Tworzy obiekt z poszczególnych części albo zgłasza wyjątek, jeśli data i czas nie są prawidłowe.

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


static createFromFormat(string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false .[method]
---------------------------------------------------------------------------------------------------------------------------
Rozszerza natywną [php:DateTime::createFromFormat] o możliwość podania strefy czasowej jako stringa.

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


Rygorystyczna walidacja
=======================

Nieprawidłowa data albo czas nigdy nie są po cichu korygowane; zawsze zgłaszany jest wyjątek. Dotyczy to każdego sposobu utworzenia albo zmiany obiektu: konstruktora, `from()`, `fromParts()` oraz metod `setDate()` i `setTime()`.

```php
new DateTimeImmutable('2024-02-31');         // zgłasza (luty nie ma 31.)
DateTimeImmutable::fromParts(2024, 2, 31);   // zgłasza
$date->setDate(2024, 2, 31);                 // zgłasza
$date->setTime(25, 0);                       // zgłasza (nie ma 25. godziny)
```


Wynik tekstowy i JSON
=====================

`__toString()` zwraca datę i czas w formacie `Y-m-d H:i:s`, więc obiekt można wypisać albo od razu konkatenować:

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

Obie klasy implementują `JsonSerializable` i serializują się do formatu ISO 8601, powszechnie używanego w JavaScripcie:

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


Dodatkowe możliwości DateTime
=============================

Zmienna klasa `DateTime` ma kilka dodatkowych elementów, które mają sens tylko dla obiektu zmiennego i dlatego **nie** wchodzą w skład `DateTimeImmutable`.

Jej metoda `from()` traktuje też małą liczbę jako przesunięcie w sekundach względem bieżącego czasu. Wariant niezmienny celowo pomija ten skrót - tam liczba jest zawsze dosłownym timestampem.

```php
DateTime::from(42); // bieżący czas plus 42 sekundy
```

`modifyClone(string $modify=''): static` zwraca zmodyfikowaną kopię i pozostawia oryginał nietknięty. Na obiekcie zmiennym daje to, co na niezmiennym zapewnia za darmo `modify()`:

```php
$original = DateTime::from('2017-02-03');
$clone = $original->modifyClone('+1 day');
$original->format('Y-m-d'); // '2017-02-03'  (bez zmian)
$clone->format('Y-m-d');    // '2017-02-04'
```

`DateTime::relativeToSeconds(string $relativeTime): int` konwertuje string z czasem względnym na sekundy: .{data-version:4.0.7}

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

Wreszcie `DateTime` definiuje stałe `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH` i `YEAR` wyrażające długość w sekundach; `MONTH` i `YEAR` są wartościami średnimi, więc używaj ich tylko do zgrubnych oszacowań.