Data e ora

Nette offre due classi per lavorare con data e ora: Nette\Utils\DateTimeImmutable (immutabile, consigliata) e 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 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:

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:

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.

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

Crea un oggetto da una stringa, da un timestamp UNIX o da un altro oggetto DateTimeInterface. null significa l'ora corrente. Solleva un'eccezione se la data e l'ora non sono valide.

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

Crea un oggetto dalle singole parti, oppure solleva un'eccezione se la data e l'ora non sono valide.

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

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

Estende il nativo DateTime::createFromFormat con la possibilità di indicare il fuso orario come stringa.

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

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:

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

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

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.

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:

$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:

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.