Fonction PHP date_date_set()

En PHP, date_date_set() et son équivalent orienté objet DateTime::setDate() définissent une nouvelle date (année, mois et jour) sur un objet DateTime existant. La partie heure de l'objet reste inchangée — seule la date du calendrier est modifiée. C'est le pendant côté date de DateTime::setTime(), qui ne modifie que l'heure.

Utilisez cette fonction lorsque vous disposez déjà d'un objet DateTime et souhaitez le déplacer vers un jour précis sans reconstruire l'objet à partir d'une chaîne.

Syntaxe

setDate() est disponible à la fois comme méthode et comme fonction procédurale. Les deux formes font exactement la même chose :

Syntaxe de DateTime::setDate() et date_date_set()

// Object-oriented style
$datetime->setDate($year, $month, $day);

// Procedural style
date_date_set($datetime, $year, $month, $day);

Où :

• $datetime est l'objet DateTime à modifier.
• $year est la nouvelle année (ex. 2024).
• $month est le nouveau mois (1–12).
• $day est le nouveau jour du mois (1–31).

La méthode retourne le même objet DateTime, ce qui permet de chaîner les appels. L'heure, les microsecondes et le fuseau horaire de l'objet sont tous préservés.

Exemple d'utilisation

Définissons une nouvelle date sur un objet DateTime tout en conservant son heure d'origine :

Exemple de la méthode PHP DateTime::setDate()

Nous créons un DateTime pour 2000-01-01 12:30:00, puis appelons setDate() pour changer la date au 15 juillet 2024. Comme setDate() ne touche que la date du calendrier, l'heure 12:30:00 est conservée. Nous utilisons ensuite la méthode format() pour afficher le résultat :

2024-07-15 12:30:00

Style procédural

Si vous le préférez (ou lisez du code plus ancien), la même modification peut s'écrire avec date_date_set(). Elle prend l'objet comme premier argument :

<?php

$date = date_create('2000-01-01');
date_date_set($date, 2024, 7, 15);
echo $date->format('Y-m-d');

Ceci affiche 2024-07-15. Ici date_create() construit l'objet — c'est l'équivalent procédural de new DateTime.

Les jours hors plage sont normalisés

Comme le reste de l'API DateTime, setDate() ne valide pas le jour par rapport à la longueur du mois. Au lieu de cela, elle normalise la valeur et reporte tout dépassement sur le mois suivant. Demander le « 31 février » donne une date en mars :

<?php

$date = new DateTime('2024-01-31');
$date->setDate(2024, 2, 31);
echo $date->format('Y-m-d');

Ceci affiche 2024-03-02 : février 2024 a 29 jours, donc le 31 est 2 jours après la fin du mois et tombe le 2 mars. Ce report est pratique pour les calculs de dates, mais c'est une source fréquente de bugs silencieux si vous attendiez une exception. Pour décaler une date d'une quantité relative, utilisez plutôt modify(), add() ou sub().

Mutable vs. Immuable

DateTime est mutable : setDate() modifie l'objet en place et retourne ce même objet. Si la valeur est partagée ailleurs dans votre code, chaque référence voit la modification. Pour éviter les mutations accidentelles, utilisez DateTimeImmutable, dont setDate() retourne une nouvelle instance et laisse l'originale intacte :

<?php

$original = new DateTimeImmutable('2000-01-01');
$changed  = $original->setDate(2024, 7, 15);

echo $original->format('Y-m-d'), ' | ', $changed->format('Y-m-d');

Ceci affiche 2000-01-01 | 2024-07-15 : $original est inchangé, et $changed contient la nouvelle date. Avec le DateTime mutable, les deux variables pointeraient vers le même objet modifié.

Méthodes associées

setDate() est rarement utilisée seule. Vous la combinerez souvent avec :

• setTime() — modifier l'heure/minute/seconde du même objet.
• setTimezone() — convertir l'objet vers un autre fuseau horaire.
• date_default_timezone_set() — définir le fuseau horaire par défaut du script.
• new DateTime / date_create() — créer l'objet en premier lieu.

Conclusion

DateTime::setDate() (et l'équivalent date_date_set()) est le moyen propre et orienté objet de modifier l'année, le mois et le jour d'un objet DateTime tout en préservant son heure et son fuseau horaire. Deux points à retenir : les jours hors plage sont normalisés sur le mois suivant plutôt que de lever une exception, et le DateTime mutable est modifié en place — utilisez DateTimeImmutable quand vous avez besoin que l'original reste intact.

Entraînement