date_interval_create_from_date_string()

Qu'est-ce que date_interval_create_from_date_string() ?

La fonction date_interval_create_from_date_string() est une fonction PHP intégrée qui construit un objet DateInterval à partir d'une chaîne de temps relatif lisible par un humain, telle que '1 day' ou '2 weeks 3 hours'. C'est l'alias procédural de la méthode statique DateInterval::createFromDateString() — les deux se comportent de manière identique.

Cette page couvre la signature de la fonction, les types de chaînes qu'elle accepte, la valeur qu'elle retourne, l'importante dépréciation en PHP 8.2, ainsi que des exemples exécutables pour ajouter et formater des intervalles.

Dépréciation : date_interval_create_from_date_string() a été dépréciée en PHP 8.2 et est prévue pour être supprimée dans une version future. Préférez le constructeur DateInterval avec une chaîne de durée ISO-8601 (par exemple new DateInterval('P1D')) dans le nouveau code. Voir Migration ci-dessous.

Syntaxe

date_interval_create_from_date_string(string $datetime): DateInterval|false

Paramètres

• $datetime — Une chaîne de temps relatif, du même type que celle comprise par strtotime(). Seules les parties relatives sont utilisées ; les parties absolues (une date ou une heure explicite) sont ignorées.

Valeur de retour

Retourne un objet DateInterval en cas de succès, ou false si la chaîne ne contient pas de parties relatives pouvant être analysées. Vérifiez toujours la valeur de retour avant de l'utiliser.

Comment ça fonctionne ?

La fonction fait passer la chaîne par le même analyseur que strtotime() et ne conserve que les parties relatives. Les formats utiles incluent :

Un moins initial (par exemple '-1 week') stocke une valeur négative directement dans la propriété concernée (ici d devient -7), donc l'ajout d'un tel intervalle à une date recule dans le temps.

Utilisation de base

<?php

$interval = date_interval_create_from_date_string('1 day');
var_dump($interval->d); // int(1)

Ici, nous créons un DateInterval représentant une durée d'un jour ; sa propriété d (jours) vaut 1.

Exemples

Exemple 1 : Ajouter un intervalle à une date

Cet exemple crée un intervalle d'un jour et l'ajoute à un objet DateTime avec DateTime::add() :

Résultat :

2023-03-04

Exemple 2 : Formater un intervalle

Cet exemple crée un intervalle d'un mois et l'affiche avec DateInterval::format(). Notez que %m n'est pas complété par des zéros — utilisez %M si vous souhaitez un zéro de tête :

Résultat :

1 months

Exemple 3 : Se prémunir contre un retour false

Si la chaîne ne contient pas de parties relatives, la fonction retourne false. Vérifiez toujours avant d'utiliser le résultat :

<?php

$interval = date_interval_create_from_date_string('not an interval');

if ($interval === false) {
    echo "Could not parse the interval.";
} else {
    echo $interval->format('%d days');
}

Résultat :

Could not parse the interval.

Migration depuis la fonction

Comme la fonction est dépréciée, préférez le constructeur DateInterval dans le nouveau code. Il accepte une chaîne de durée ISO-8601 : P commence une période, et T sépare la partie date de la partie heure.

<?php

// Deprecated:
$old = date_interval_create_from_date_string('1 day');

// Recommended replacement:
$new = new DateInterval('P1D'); // P = period, 1D = 1 day

echo $new->format('%d day'); // 1 day

Résultat :

1 day

Conversions courantes : '1 day' → P1D, '2 weeks' → P14D, '1 month' → P1M, '2 hours 30 minutes' → PT2H30M.

Conseils de performance

• Construisez un intervalle une seule fois et réutilisez-le ; évitez de recréer le même DateInterval dans des boucles serrées.
• L'analyse d'une chaîne relative demande légèrement plus de travail que le constructeur, donc préférez new DateInterval('P1D') lorsque la durée est fixe et connue à l'avance.

Voir aussi

• date_interval_format() — formater un DateInterval pour l'affichage.
• date_add() — ajouter un intervalle à une date.
• date_diff() — obtenir le DateInterval entre deux dates.
• strtotime() — l'analyseur de temps relatif sur lequel cette fonction s'appuie.

Conclusion

date_interval_create_from_date_string() transforme une chaîne de temps relatif en DateInterval, retournant false lorsque la chaîne ne peut pas être analysée. Elle a été dépréciée en PHP 8.2, donc pour le nouveau code, préférez le constructeur DateInterval avec une durée ISO-8601 (new DateInterval('P1D')). Lorsque vous l'utilisez, validez toujours la valeur de retour avant de vous fier à l'objet résultant.

Pratique