PHP Date

Introduction

Presque toute application doit lire, formater ou effectuer des calculs sur des dates : entrées de journal, libellés « publié il y a 3 jours », planification, vérifications d'expiration. PHP met à votre disposition deux ensembles d'outils parallèles pour cela :

• Les fonctions procédurales basées sur le timestamp Unix — un entier comptant les secondes depuis le 1er janvier 1970, 00:00:00 UTC. time(), date(), strtotime() et mktime() en font partie.
• L'API orientée objet DateTime — DateTime, DateTimeImmutable, DateTimeZone et DateInterval — qui est plus sûre pour les calculs et la gestion des fuseaux horaires.

Cette page couvre les fonctions et classes les plus utilisées, quand choisir l'une ou l'autre, et le piège lié aux fuseaux horaires qui trompe presque tout le monde.

Note sur les fuseaux horaires

Par défaut, PHP utilise le fuseau horaire configuré dans php.ini (le paramètre date.timezone). Si ce paramètre n'est pas défini, vous pouvez obtenir des résultats incohérents d'un serveur à l'autre. Définissez-le explicitement en haut de votre script, ou passez un DateTimeZone à chaque objet :

date_default_timezone_set('UTC');

Consultez PHP Timezones pour la liste complète des identifiants valides et pour savoir comment convertir entre les zones.

La fonction date()

date(string $format, ?int $timestamp = null) formate un timestamp en une chaîne lisible par l'humain. Lorsque vous omettez le timestamp, elle utilise l'heure actuelle. C'est la fonction de référence pour afficher les dates.

echo date('Y-m-d H:i:s'); // e.g. 2023-10-25 14:30:00
echo date('l, F j, Y');   // e.g. Wednesday, October 25, 2023

La chaîne format est composée de caractères de substitution à un seul caractère. Les plus courants :

Pour afficher une lettre littérale qui est aussi un caractère de format, échappez-la avec un antislash : date('\T\o\d\a\y: Y-m-d').

La fonction time()

time() retourne le timestamp Unix actuel sous forme d'entier. Utilisez-la dès que vous avez besoin d'un « maintenant » numérique à stocker, comparer ou utiliser dans des calculs.

$now = time();
echo $now; // an integer such as 1698241800

// One hour from now:
echo date('Y-m-d H:i:s', $now + 3600);

Un timestamp étant simplement un entier de secondes, vous pouvez ajouter ou soustraire des durées directement (+ 3600 pour une heure, + 86400 pour un jour). Pour tout ce qui est plus complexe que quelques décalages fixes, préférez l'arithmétique DateTime ci-dessous.

La fonction strtotime()

strtotime(string $datetime, ?int $baseTimestamp = null) analyse une date/heure textuelle en anglais et la convertit en timestamp, en retournant false en cas d'échec. Elle comprend aussi bien les chaînes absolues que les expressions relatives.

echo strtotime('2023-10-25 14:30:00'); // 1698244200 (UTC)
echo "\n";
var_dump(strtotime('next monday'));    // a future timestamp, or false if unparseable

$tomorrow = strtotime('+1 day');
echo date('Y-m-d', $tomorrow);

Vérifiez toujours si le résultat est false avant de l'utiliser, car une faute de frappe échoue silencieusement sans lever d'exception.

La fonction mktime()

mktime(int $hour, int $minute, int $second, int $month, int $day, int $year) construit un timestamp à partir de composants individuels. Notez que l'ordre des arguments est d'abord l'heure, puis la date.

$timestamp = mktime(0, 0, 0, 12, 31, 2023);
echo date('Y-m-d', $timestamp); // 2023-12-31

mktime() normalise les valeurs hors plage, ce qui est pratique : mktime(0, 0, 0, 13, 1, 2023) convertit le « mois 13 » en janvier 2024.

La classe DateTime

new DateTime(string $datetime = 'now', ?DateTimeZone $timezone = null) encapsule une date dans un objet que vous pouvez formater, comparer et modifier par des appels de méthode. (La fonction date_create() est un alias procédural du même constructeur.)

$date = new DateTime('2023-10-25', new DateTimeZone('UTC'));
echo $date->format('Y-m-d'); // 2023-10-25

DateTime est mutable — des méthodes comme modify() modifient l'objet en place. C'est la source de bugs subtils lorsqu'un objet est partagé, c'est pourquoi la version immuable ci-dessous est généralement préférée.

La classe DateTimeImmutable

DateTimeImmutable possède la même API que DateTime, mais chaque méthode de modification retourne un nouvel objet et laisse l'original intact. Pour le code moderne, c'est l'option par défaut la plus sûre.

$date = new DateTimeImmutable('2023-10-25');
$newDate = $date->modify('+1 day');
echo $date->format('Y-m-d');    // 2023-10-25 (unchanged)
echo "\n";
echo $newDate->format('Y-m-d'); // 2023-10-26

La méthode DateTime::format()

format(string $format) convertit un objet DateTime ou DateTimeImmutable en chaîne de caractères. Elle accepte les mêmes caractères de format que la fonction date().

$date = new DateTimeImmutable('2023-10-25 14:30:00');
echo $date->format('l, F j, Y'); // Wednesday, October 25, 2023

Arithmétique et différences de dates

L'API orientée objet excelle pour les calculs. Utilisez DateInterval (chaînes de durée ISO-8601) pour ajouter ou soustraire, et diff() pour comparer deux dates :

$start = new DateTimeImmutable('2023-10-25');
$later = $start->add(new DateInterval('P10D')); // P10D = 10 days
echo $later->format('Y-m-d'); // 2023-11-04

$diff = $start->diff(new DateTimeImmutable('2023-12-31'));
echo "\n" . $diff->days . ' days apart'; // 67 days apart

Choisir le bon outil

• Vous avez besoin d'un « maintenant » formaté rapidement ? Utilisez date().
• Vous stockez ou comparez un moment numériquement ? Utilisez time() / les timestamps Unix.
• Vous analysez une saisie utilisateur ou un fichier journal ? Utilisez strtotime() (et vérifiez si le résultat est false).
• Vous faites des calculs, des différences ou des conversions de fuseau horaire ? Utilisez DateTimeImmutable avec DateInterval.

Pièges courants

• Fuseau horaire non défini. Sans date_default_timezone_set() ni valeur dans php.ini, les résultats varient selon le serveur. Définissez-le une fois, tôt dans l'exécution.
• strtotime() retourne false pour les chaînes non reconnues — elle ne lève jamais d'exception, donc validez toujours le résultat.
• DateTime est mutable. modify() modifie l'original ; préférez DateTimeImmutable pour éviter les surprises liées aux états partagés.
• Les timestamps sont des secondes UTC. Les formater avec date() applique le fuseau horaire actuel, donc le même entier s'affiche différemment selon vos paramètres.

Conclusion

PHP vous offre une boîte à outils de timestamps procédurale (date(), time(), strtotime(), mktime()) et une orientée objet (DateTime, DateTimeImmutable). Appuyez-vous sur les timestamps simples pour l'affichage et le stockage, et sur DateTimeImmutable pour les calculs et la logique sensible aux fuseaux horaires. Pour aller plus loin, consultez PHP Date and Time, la référence date(), strtotime() et mktime().

Pratique