Analyse de dates en PHP

Les dates arrivent souvent sous forme de chaînes brutes — depuis un formulaire, un fichier CSV ou une réponse API — et PHP ne peut pas deviner leur mise en forme sans que vous le lui indiquiez. La fonction date_parse_from_format() vous permet d'analyser une chaîne de date selon un format explicite et d'inspecter le résultat, y compris les éventuelles erreurs ou avertissements. Cette page explique le fonctionnement de la fonction, comment lire sa valeur de retour, comment valider des entrées et quand utiliser un autre outil comme DateTime ou strtotime().

Ce que signifie l'analyse de dates

L'analyse de dates est le processus qui consiste à transformer une chaîne comme "2023-03-03" en données structurées — une année, un mois, un jour, etc. — que votre programme peut exploiter. La difficulté réside dans l'ambiguïté : 03/04/2023 peut désigner le 4 mars ou le 3 avril selon la convention, et 2023-13-45 ressemble à une date mais n'en est pas une valide.

date_parse_from_format() supprime cette ambiguïté en vous obligeant à fournir le format exact au préalable. Elle lit la chaîne strictement selon ce format et vous indique ce qu'elle a trouvé, afin que vous puissiez décider si l'entrée était valide.

La fonction date_parse_from_format()

date_parse_from_format() analyse une chaîne de date à l'aide d'un format spécifique et retourne un array associatif décrivant la date analysée : année, mois, jour, heure, minute, seconde, ainsi que les avertissements et erreurs collectés lors de la lecture de la chaîne.

Syntaxe

date_parse_from_format(string $format, string $datetime): array

• $format — une chaîne de format utilisant les mêmes espaces réservés que date(), par exemple Y-m-d pour 2023-03-03 ou d/m/Y pour 03/03/2023.
• $datetime — la chaîne de date à analyser.

La fonction retourne toujours un array ; elle ne lève jamais d'exception. Pour savoir si l'analyse a réussi, vous devez vérifier les clés error_count et warning_count.

Un exemple de base

La sortie de ce code sera :

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

La fonction a analysé "2023-03-03 10:30:00" selon le format Y-m-d H:i:s et a rempli chaque composant. Vous pouvez lire les valeurs individuelles directement depuis l'array, comme $date_array['year'] ou $date_array['month']. Lorsqu'un composant est absent de la chaîne de format, sa valeur est retournée sous la forme false (affiché comme valeur vide par print_r).

Analyser des formats personnalisés

Les espaces réservés de format sont les mêmes que ceux utilisés par date(), ainsi tout format que vous pouvez produire peut également être analysé. L'exemple ci-dessous lit une date au style européen jour/mois/année :

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

Cela affiche :

Day:   3
Month: 3
Year:  2023

Comme seuls d, m et Y apparaissent dans le format, les clés hour, minute et second retournent false.

Valider le résultat : erreurs et avertissements

date_parse_from_format() ne lève jamais d'exception — même en cas d'entrée invalide, elle retourne un array. Deux clés vous indiquent si l'entrée était exploitable :

• error_count compte les caractères qui ne correspondaient pas du tout au format.
• warning_count compte les valeurs qui correspondaient au format mais n'ont aucun sens, comme le mois 13 ou le jour 45.

Une chaîne qui ne correspond pas au format produit des erreurs :

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

Une chaîne qui correspond au format mais n'est pas une date réelle produit un avertissement :

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Vérifiez toujours les deux compteurs avant de vous fier aux valeurs analysées :

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

Quand utiliser une autre fonction

date_parse_from_format() est idéale quand vous souhaitez un rapport détaillé tenant compte du format — notamment pour valider des entrées. Si vous avez simplement besoin d'une valeur de date utilisable, d'autres outils sont plus pratiques :

• DateTime::createFromFormat($format, $string) retourne un objet DateTime prêt à l'emploi que vous pouvez formater ou sur lequel vous pouvez effectuer des calculs. Voir PHP date et heure.
• strtotime() devine le format pour vous et retourne un horodatage Unix — pratique pour les chaînes courantes et non ambiguës, mais plus risqué pour les formats spécifiques aux paramètres régionaux.
• date_parse() est similaire à cette fonction mais sans chaîne de format ; elle tente d'interpréter la date par elle-même.

Conclusion

date_parse_from_format() analyse une chaîne de date selon un format explicite et retourne un array associatif détaillé, ce qui en fait un outil idéal pour valider des dates saisies par l'utilisateur. Rappelez-vous qu'elle ne lève jamais d'exception — vérifiez error_count et warning_count avant d'utiliser le résultat. Lorsque vous avez besoin d'un objet DateTime ou d'un horodatage, utilisez plutôt DateTime::createFromFormat() ou strtotime().

Pratique