date_format()

date_format()

Introduction

Les dates et les heures sont omniprésentes dans les applications réelles : horodatages sur les articles de blog, dates de commande dans une boutique en ligne, entrées de journaux, événements de calendrier. PHP stocke ces moments en interne d'une façon non lisible par un être humain, il vous faut donc un moyen de transformer un objet date en chaîne lisible — "2023-03-03", "Friday, March 3rd" ou "03/03/2023 1:00 PM". C'est précisément ce que fait date_format().

Ce chapitre explique ce qu'est date_format(), sa syntaxe, les caractères de format les plus utiles, ainsi que les pièges liés aux fuseaux horaires et à l'immuabilité.

Qu'est-ce que la fonction date_format() ?

La fonction date_format() formate un objet DateTime sous forme de chaîne selon un motif que vous fournissez. C'est un alias procédural de la méthode orientée objet DateTime::format() — les deux produisent des résultats identiques, utilisez donc le style qui convient le mieux à votre base de code :

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Syntaxe

date_format(DateTimeInterface $object, string $format): string

• $object — une instance de DateTime (ou DateTimeImmutable). C'est la date que vous souhaitez afficher.
• $format — une chaîne construite à partir de caractères de format (tels que Y, m, d). Tout caractère qui n'est pas un caractère de format est imprimé tel quel.
• Valeur de retour — la date formatée sous forme de chaîne.

Comment utiliser la fonction date_format()

Créez d'abord un objet date avec la classe DateTime, intégrée à PHP :

<?php

$date = new DateTime('2023-03-03');

Cela crée une date fixée au 3 mars 2023 à minuit. Par défaut, DateTime utilise le fuseau horaire configuré sur le serveur — ce qui signifie que le même code peut produire une sortie différente selon les machines. Pour des résultats prévisibles, définissez toujours le fuseau horaire explicitement :

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Formatez ensuite la date comme vous le souhaitez :

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

Pour les applications PHP modernes, préférez DateTimeImmutable à DateTime. Des méthodes comme modify() modifient un DateTime en place, ce qui est une source fréquente de bogues lorsque l'objet est transmis à différentes fonctions ; DateTimeImmutable renvoie un nouvel objet à la place et fonctionne avec date_format() exactement de la même manière :

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Formats de date courants

Il existe de nombreuses façons de formater les dates avec la fonction date_format(). Voici quelques-uns des formats les plus courants :

• Y-m-d : La date au format YYYY-MM-DD.
• d/m/Y : La date au format DD/MM/YYYY.
• m/d/Y : La date au format MM/DD/YYYY.
• H:i:s : L'heure au format 24 heures (ex. : 13:00:00).
• h:i:s a : L'heure au format 12 heures (ex. : 01:00:00 am).

Caractères de format

En plus des formats courants ci-dessus, vous pouvez construire votre propre motif à partir de caractères de format individuels. Voici ceux que vous utiliserez le plus souvent :

• Y : L'année en quatre chiffres (ex. : 2023).
• y : L'année en deux chiffres (ex. : 23).
• m : Le mois sous forme de nombre à deux chiffres (ex. : 03).
• M : Le nom abrégé du mois (ex. : Mar).
• F : Le nom complet du mois (ex. : March).
• d : Le jour du mois sous forme de nombre à deux chiffres (ex. : 03).
• D : Le nom abrégé du jour (ex. : Fri).
• l : Le nom complet du jour (ex. : Friday).
• j : Le jour du mois sans zéros de tête (ex. : 3).
• S : Suffixe ordinal anglais pour le jour du mois (ex. : st, nd, rd, th).
• H : L'heure au format 24 heures (ex. : 13).
• h : L'heure au format 12 heures (ex. : 01).
• i : Les minutes sous forme de nombre à deux chiffres (ex. : 05).
• s : Les secondes sous forme de nombre à deux chiffres (ex. : 30).
• a : am ou pm.

Pour la liste complète de tous les caractères pris en charge, consultez PHP date and time et le chapitre date() — date_format() utilise les mêmes caractères.

Voici un exemple de format de date personnalisé :

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

Pour afficher un caractère de format littéralement plutôt que de le faire interpréter, faites-le précéder d'un antislash :

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Les deux fonctions formatent des dates, mais elles acceptent des entrées différentes :

• date() fonctionne sur un horodatage Unix (un entier) et utilise par défaut « maintenant ». Utilisez-la pour un formatage rapide, indépendant du fuseau horaire : date('Y-m-d').
• date_format() fonctionne sur un objet DateTime, qui transporte son propre fuseau horaire et prend en charge l'arithmétique (ajout de jours, calcul de différences) avant le formatage. Utilisez-la lorsque vous avez besoin de manipuler la date.

Si vous disposez d'une chaîne telle que "3 March 2023", créez d'abord un objet DateTime — date_create_from_format() et strtotime() sont les points d'entrée habituels.

Conclusion

La fonction date_format() en PHP offre un moyen simple de formater un objet DateTime sous forme de chaîne lisible. En comprenant les caractères de format disponibles et les bonnes pratiques — définir le fuseau horaire explicitement et préférer DateTimeImmutable — vous pouvez garantir une sortie de date précise et prévisible dans tous les environnements où votre code s'exécute.

Practice