Data e ora
**********

.[perex]
Nette offre due classi per lavorare con data e ora: [api:Nette\Utils\DateTimeImmutable] (immutabile, consigliata) e [api:Nette\Utils\DateTime] (mutabile). Entrambe estendono le classi native di PHP, quindi ogni metodo nativo resta disponibile, e vi aggiungono le stesse due migliorie.

Innanzitutto sono **rigorose**. Mentre PHP accetta in silenzio date non valide come `0000-00-00` (che converte in `-0001-11-30`) o `2024-02-31` (che converte in `2024-03-02`), queste classi sollevano invece un'eccezione.

In secondo luogo **correggono il comportamento** durante i passaggi all'ora legale (DST), dove in PHP nativo l'aggiunta di un tempo relativo (per esempio `+100 minuti`) può "portare a un orario precedente":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes rispetto all'aggiunta di un periodo più breve (per esempio `+50 minuti`). Queste classi garantiscono che l'aritmetica funzioni in modo intuitivo e che `+100 minuti` sia sempre più di `+50 minuti`.

Installazione:

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


Immutabile o mutabile?
======================

La classe `DateTimeImmutable` è disponibile dalla versione 4.1.5 ed è la scelta consigliata. Ogni metodo che modifica restituisce una **nuova istanza** invece di cambiare l'originale, quindi un oggetto che avete salvato o passato a una funzione non può mai cambiare inaspettatamente:

```php
use Nette\Utils\DateTimeImmutable;

$date = new DateTimeImmutable('2024-02-26');
$next = $date->modify('+1 day');
echo $date; // 2024-02-26 00:00:00  (invariato)
echo $next; // 2024-02-27 00:00:00  (un nuovo oggetto)
```

`DateTime` è mutabile: la stessa chiamata cambia l'oggetto sul posto. Non è deprecata, ma per il codice nuovo è preferibile la variante immutabile.

```php
use Nette\Utils\DateTime;

$date = new DateTime('2024-02-26');
$date->modify('+1 day');
echo $date; // 2024-02-27 00:00:00  (l'originale è cambiato)
```

Poiché entrambe le classi estendono quelle native, continuate a usare i metodi che già conoscete: `format()`, `getTimestamp()`, `add()`, `sub()`, `diff()`, `setTimezone()`, gli operatori di confronto e così via. Su `DateTimeImmutable` tutti quelli che modificano restituiscono una nuova istanza. Il resto di questa pagina descrive solo ciò che Nette aggiunge; se non indicato diversamente, tutto funziona allo stesso modo in entrambe le classi.


Creare gli oggetti
==================


static from(string|int|\DateTimeInterface|null $time): static .[method]
-----------------------------------------------------------------------
Crea un oggetto da una stringa, da un timestamp UNIX o da un altro oggetto [php:DateTimeInterface]. `null` significa l'ora corrente. Solleva un'eccezione se la data e l'ora non sono valide.

```php
DateTimeImmutable::from(1_138_013_640); // da un timestamp UNIX, con il fuso orario predefinito
DateTimeImmutable::from('1994-02-26 04:15:32'); // da una stringa
DateTimeImmutable::from('1994-02-26'); // da una data, l'ora sarà 00:00:00
DateTimeImmutable::from(null); // la data e l'ora correnti
```


static fromParts(int $year, int $month, int $day, int $hour=0, int $minute=0, float $second=0.0): static .[method]
------------------------------------------------------------------------------------------------------------------
Crea un oggetto dalle singole parti, oppure solleva un'eccezione se la data e l'ora non sono valide.

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


static createFromFormat(string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false .[method]
---------------------------------------------------------------------------------------------------------------------------
Estende il nativo [php:DateTime::createFromFormat] con la possibilità di indicare il fuso orario come stringa.

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


Validazione rigorosa
====================

Una data o un'ora non valide non vengono mai corrette in silenzio: viene sempre sollevata un'eccezione. Questo vale per ogni modo di creare o modificare un oggetto: il costruttore, `from()`, `fromParts()` e i metodi `setDate()` e `setTime()`.

```php
new DateTimeImmutable('2024-02-31');         // solleva un'eccezione (febbraio non ha il 31)
DateTimeImmutable::fromParts(2024, 2, 31);   // solleva un'eccezione
$date->setDate(2024, 2, 31);                 // solleva un'eccezione
$date->setTime(25, 0);                       // solleva un'eccezione (non esiste la 25ª ora)
```


Output testuale e JSON
======================

`__toString()` restituisce la data e l'ora nel formato `Y-m-d H:i:s`, quindi un oggetto si può stampare o concatenare direttamente:

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

Entrambe le classi implementano `JsonSerializable` e si serializzano nel formato ISO 8601, molto usato in JavaScript:

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


Funzionalità aggiuntive di DateTime
===================================

La `DateTime` mutabile porta con sé alcuni membri in più che hanno senso solo per un oggetto mutabile e che quindi **non** fanno parte di `DateTimeImmutable`.

Il suo metodo `from()` tratta inoltre un numero piccolo come uno scostamento in secondi dall'ora corrente. La variante immutabile omette volutamente questa scorciatoia: lì un numero è sempre un timestamp letterale.

```php
DateTime::from(42); // l'ora corrente più 42 secondi
```

`modifyClone(string $modify=''): static` restituisce una copia modificata e lascia intatto l'originale. Su un oggetto mutabile offre ciò che su quello immutabile `modify()` dà gratis:

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

`DateTime::relativeToSeconds(string $relativeTime): int` converte in secondi una stringa di tempo relativo: .{data-version:4.0.7}

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

Infine `DateTime` definisce le costanti `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH` e `YEAR`, che esprimono una durata in secondi; `MONTH` e `YEAR` sono valori medi, quindi usateli solo per stime approssimative.