date_create()

Introduction

La fonction date_create() de PHP est la manière procédurale de construire un objet DateTime — la brique de base orientée objet pour presque tous les travaux liés aux dates et heures en PHP. Cet article couvre sa syntaxe et ses paramètres, montre comment lire un DateTime une fois obtenu, explique ce qui se passe en cas d'échec de l'analyse, et pointe vers les fonctions associées que vous utiliserez ensuite.

date_create() est simplement un alias de new DateTime(). Les deux sont interchangeables, utilisez donc celui qui rend votre code plus lisible. Une raison courante de préférer date_create() est que, contrairement au constructeur, elle retourne false au lieu de lever une exception en cas de chaîne d'entrée invalide — ce qui peut être géré sans bloc try/catch.

La fonction date_create()

La fonction date_create() est une fonction PHP intégrée qui crée un nouvel objet DateTime. Elle prend un paramètre optionnel qui spécifie la date et l'heure dans un format reconnu par la fonction strtotime(). Si aucun paramètre n'est passé, la fonction retourne un objet DateTime représentant la date et l'heure actuelles.

Syntaxe

La syntaxe de la fonction date_create() est la suivante :

Syntaxe de la fonction date_create() en PHP

date_create(string $datetime = "now", ?DateTimeZone $timezone = null): DateTime|false

Le premier paramètre, $time, spécifie la date et l'heure pour créer l'objet DateTime. Il est optionnel et a comme valeur par défaut "now". Le second paramètre, $timezone, spécifie le fuseau horaire à utiliser. Il est également optionnel et a comme valeur par défaut NULL.

Paramètres

Examinons de plus près les paramètres de la fonction date_create() :

• $datetime (optionnel) : Spécifie la date et l'heure pour créer l'objet DateTime. Il peut s'agir de n'importe quelle chaîne dans un format reconnu par la fonction strtotime() — une date absolue comme "2022-12-31", une expression relative comme "next monday" ou "+1 week", ou un horodatage UNIX préfixé par @ (par exemple "@1672531199"). La valeur par défaut "now" produit la date et l'heure actuelles.
• $timezone (optionnel) : Un objet DateTimeZone spécifiant le fuseau horaire. S'il est omis (ou null), le fuseau horaire par défaut du script est utilisé. Remarque : ce paramètre est ignoré lorsque $datetime est un horodatage UNIX (@...) ou contient déjà un décalage de fuseau horaire tel que "2022-12-31 23:59:59+02:00".

Valeur de retour

En cas de succès, date_create() retourne un objet DateTime. En cas d'échec — par exemple lorsque $datetime ne peut pas être analysé — elle retourne false plutôt que de lever une exception. Cela permet de tester le résultat avec une simple condition :

<?php

$date = date_create('not a real date');

if ($date === false) {
    echo 'Could not parse the date.';
} else {
    echo $date->format('Y-m-d');
}
// Output: Could not parse the date.

Exemples

Voici quelques exemples d'utilisation de la fonction date_create() :

Exemple d'utilisation de la fonction date_create() en PHP

Utilisation de chaînes de dates relatives

Puisque date_create() accepte tout ce que strtotime() comprend, vous pouvez construire des dates relatives à « maintenant » sans aucun calcul arithmétique :

<?php

$today = date_create();
echo $today->format('l') . "\n";          // e.g. Output: Thursday

$nextWeek = date_create('+1 week');
echo $nextWeek->format('Y-m-d') . "\n";   // 7 days from today

$firstOfMonth = date_create('first day of this month');
echo $firstOfMonth->format('Y-m-d');       // e.g. 2023-03-01

Utilisation du résultat

Une fois que vous avez un objet DateTime, vous le formatez généralement pour l'affichage ou le comparez avec une autre date :

<?php

$start = date_create('2022-01-01');
$end   = date_create('2022-12-31');

// Format the object as a string
echo $end->format('F j, Y') . "\n";   // Output: December 31, 2022

// Compare two DateTime objects directly
echo ($end > $start ? 'end is later' : 'start is later');
// Output: end is later

Utilisez date_format() (ou la méthode ->format() illustrée ci-dessus) pour afficher l'objet, et date_diff() pour mesurer l'intervalle entre deux objets DateTime.

Fonctions associées

• date_create_from_format() — crée un DateTime à partir d'une chaîne utilisant un format personnalisé que vous spécifiez, au lieu de s'appuyer sur les heuristiques de strtotime().
• date_format() — convertit un objet DateTime en chaîne formatée.
• date_add() — ajoute un DateInterval à un DateTime.
• strtotime() — l'analyseur qui alimente l'argument $datetime ; retourne un horodatage UNIX plutôt qu'un objet.

Conclusion

La fonction date_create() est le point d'entrée procédural pour travailler avec les objets DateTime de PHP. Elle accepte aussi bien les chaînes de dates absolues que relatives, prend optionnellement un fuseau horaire en paramètre, et retourne false en cas d'échec afin que vous puissiez valider les entrées sans gestion d'exceptions. Une fois que vous disposez d'un DateTime, formatez-le avec ->format() et comparez ou soustrayez directement les objets. Pour analyser des entrées non standard, utilisez date_create_from_format() ; pour afficher les résultats, utilisez date_format().

Pratique