Date et heure

Nette propose deux classes pour travailler avec la date et l'heure : Nette\Utils\DateTimeImmutable (immuable, recommandée) et Nette\Utils\DateTime (muable). Toutes deux étendent les classes natives de PHP, si bien que chaque méthode native reste disponible, et y ajoutent les deux mêmes améliorations.

Premièrement, elles sont strictes. Là où PHP accepte silencieusement des dates invalides comme 0000-00-00 (converti en -0001-11-30) ou 2024-02-31 (converti en 2024-03-02), ces classes lèvent une exception.

Deuxièmement, elles corrigent le comportement lors des passages à l'heure d'été (DST), où l'ajout d'un temps relatif en PHP natif (par ex. +100 minutes) peut aboutir à une heure antérieure à l'ajout d'une durée plus courte (par ex. +50 minutes). Ces classes garantissent que l'arithmétique fonctionne de façon intuitive et que +100 minutes donne toujours plus que +50 minutes.

Installation :

composer require nette/utils

Immuable ou muable ?

La classe DateTimeImmutable est disponible depuis la version 4.1.5 et constitue le choix recommandé. Chaque méthode modificatrice retourne une nouvelle instance au lieu de changer l'originale : un objet que vous avez stocké ou passé à une fonction ne peut donc jamais changer à votre insu :

use Nette\Utils\DateTimeImmutable;

$date = new DateTimeImmutable('2024-02-26');
$next = $date->modify('+1 day');
echo $date; // 2024-02-26 00:00:00  (inchangé)
echo $next; // 2024-02-27 00:00:00  (un nouvel objet)

DateTime est muable : le même appel modifie l'objet sur place. Elle n'est pas dépréciée, mais pour du code neuf, la variante immuable est préférable.

use Nette\Utils\DateTime;

$date = new DateTime('2024-02-26');
$date->modify('+1 day');
echo $date; // 2024-02-27 00:00:00  (l'original a changé)

Comme les deux classes étendent les classes natives, vous continuez d'employer les méthodes que vous connaissez déjà : format(), getTimestamp(), add(), sub(), diff(), setTimezone(), les opérateurs de comparaison, etc. Sur DateTimeImmutable, toutes les méthodes modificatrices retournent une nouvelle instance. La suite de cette page décrit uniquement ce que Nette ajoute par-dessus ; sauf mention contraire, tout fonctionne de la même façon dans les deux classes.

Création des objets

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

Crée un objet à partir d'une chaîne, d'un timestamp UNIX ou d'un autre objet DateTimeInterface. null signifie l'heure actuelle. Lève une exception si la date et l'heure ne sont pas valides.

DateTimeImmutable::from(1_138_013_640); // depuis un timestamp UNIX, avec le fuseau horaire par défaut
DateTimeImmutable::from('1994-02-26 04:15:32'); // depuis une chaîne
DateTimeImmutable::from('1994-02-26'); // depuis une date, l'heure sera 00:00:00
DateTimeImmutable::from(null); // la date et l'heure actuelles

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

Crée un objet à partir de composants individuels, ou lève une exception si la date et l'heure ne sont pas valides.

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

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

Étend la méthode native DateTime::createFromFormat avec la possibilité d'indiquer le fuseau horaire sous forme de chaîne.

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

Validation stricte

Une date ou une heure invalide n'est jamais corrigée en silence : elle lève toujours une exception. Cela vaut pour toutes les façons de créer ou de modifier un objet : le constructeur, from(), fromParts() et les méthodes setDate() et setTime().

new DateTimeImmutable('2024-02-31');         // lève une exception (février n'a pas de 31)
DateTimeImmutable::fromParts(2024, 2, 31);   // lève une exception
$date->setDate(2024, 2, 31);                 // lève une exception
$date->setTime(25, 0);                       // lève une exception (il n'y a pas de 25e heure)

Sortie texte et JSON

__toString() retourne la date et l'heure au format Y-m-d H:i:s : un objet peut donc être affiché ou concaténé directement :

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

Les deux classes implémentent JsonSerializable et se sérialisent au format ISO 8601, couramment utilisé en JavaScript :

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

Fonctionnalités supplémentaires de DateTime

La classe muable DateTime porte quelques membres supplémentaires qui n'ont de sens que pour un objet muable et qui ne font donc pas partie de DateTimeImmutable.

Sa méthode from() traite en outre un petit nombre comme un décalage en secondes par rapport à l'heure actuelle. La variante immuable omet volontairement ce raccourci : un nombre y est toujours un timestamp littéral.

DateTime::from(42); // l'heure actuelle plus 42 secondes

modifyClone(string $modify=''): static retourne une copie modifiée et laisse l'original intact. Sur un objet muable, elle offre ce que modify() donne gratuitement sur l'objet immuable :

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

DateTime::relativeToSeconds(string $relativeTime): int convertit une chaîne de temps relatif en secondes :

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

Enfin, DateTime définit les constantes MINUTE, HOUR, DAY, WEEK, MONTH et YEAR, qui expriment une durée en secondes ; MONTH et YEAR sont des moyennes, ne vous en servez donc que pour des estimations approximatives.