Fonction PHP date_create_from_format : syntaxe et exemples

La fonction date_create_from_format() analyse une chaîne de date écrite dans votre format — pas seulement les formats que PHP devine — et retourne un objet DateTime. Utilisez-la chaque fois que vous recevez une date dans une mise en forme fixe et non standard (un export CSV, une API tierce, un formulaire utilisateur) et que vous devez la lire de manière fiable.

Cette page couvre la syntaxe, des exemples exécutables, le paramètre de fuseau horaire, la détection des échecs d'analyse, et les différences entre cette fonction et strtotime() ainsi que date_parse_from_format().

Syntaxe

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

• $format — la mise en forme de la chaîne d'entrée, écrite avec les mêmes caractères de format que la fonction date(). Par exemple, "Y-m-d H:i:s" correspond à "2023-03-02 17:30:45".
• $datetime — la chaîne de date à analyser. Sa mise en forme doit correspondre à $format.
• $timezone — (facultatif) un DateTimeZone pour l'objet résultant. Si omis, le fuseau horaire par défaut actuel (défini via date_default_timezone_set()) est utilisé. Ce paramètre est ignoré si $format contient déjà un caractère de fuseau horaire tel que e, O, P ou T.

La fonction retourne un objet DateTime en cas de succès, ou false si la chaîne ne correspond pas au format.

date_create_from_format() est l'alias procédural de la méthode statique DateTime::createFromFormat() — elles se comportent de manière identique.

Exemples

Analyser une chaîne de date standard

La fonction lit "2023-03-02 17:30:45" selon "Y-m-d H:i:s" et retourne un objet DateTime. Appeler format() dessus permet de réafficher la date dans n'importe quelle mise en forme souhaitée.

Reformater une date non standard

Ici, l'entrée utilise un jour, un nom de mois en trois lettres et une année à quatre chiffres (j-M-Y). La sortie est affichée dans l'ordre ISO (Y-m-d) — la preuve qu'une fois qu'une date est un objet DateTime, vous êtes libre de l'afficher comme bon vous semble.

Réinitialiser l'heure avec !

Si votre format ne contient pas de champs d'heure, les parties manquantes prennent par défaut l'heure, les minutes et les secondes courantes — ce qui est rarement ce que vous souhaitez pour une valeur date seule. Préfixez le format avec ! pour réinitialiser tous les champs non spécifiés à l'époque Unix (00:00:00) :

<?php

$date = date_create_from_format('!Y-m-d', '2023-03-02');
echo $date->format('Y-m-d H:i:s'); // Output: 2023-03-02 00:00:00

Fournir un fuseau horaire

<?php

$tz = new DateTimeZone('Europe/Paris');
$date = date_create_from_format('Y-m-d H:i:s', '2023-03-02 17:30:45', $tz);
echo $date->format('Y-m-d H:i:s P'); // Output: 2023-03-02 17:30:45 +01:00

Le troisième argument ancre la date analysée à l'heure de Paris, de sorte que le jeton P indique le décalage +01:00.

Gestion des échecs d'analyse

Lorsque la chaîne ne correspond pas au format, la fonction retourne false plutôt que de lever une exception. Vérifiez toujours ce cas, et consultez DateTime::getLastErrors() pour les détails :

<?php

$date = date_create_from_format('Y-m-d', 'not-a-date');

if ($date === false) {
    $errors = DateTime::getLastErrors();
    echo "Parse failed: {$errors['error_count']} error(s)\n";
    // Output: Parse failed: 3 error(s)
}

Comme false est une valeur fausse, un simple if (!$date) fonctionne également — mais une vérification stricte === false est plus sûre lorsqu'une valeur vide pourrait légitimement signifier autre chose.

Comparaison avec d'autres fonctions de date

Préférez date_create_from_format() lorsque la mise en forme est fixe et que vous souhaitez un objet DateTime complet à manipuler. Utilisez strtotime() pour les chaînes en langage naturel comme "next Friday", et date_parse_from_format() lorsque vous n'avez besoin que des valeurs brutes année/mois/jour sans construire d'objet.

Conclusion

date_create_from_format() transforme une chaîne dans une mise en forme arbitraire et connue en un objet DateTime que vous pouvez formater, comparer et manipuler avec le reste de l'API de dates de PHP. Pensez à utiliser le préfixe ! pour les valeurs date seules, passez un DateTimeZone lorsque le fuseau horaire source est important, et vérifiez toujours le retour false.

Pratique