Fonction PHP date_time_set()

En PHP, la méthode DateTime::setTime() est utilisée pour définir une nouvelle heure pour un objet DateTime donné. Cette méthode fait partie de la classe PHP DateTime et permet de modifier la partie heure d'un objet date/heure avec une nouvelle valeur.

Syntaxe

La syntaxe de la méthode DateTime::setTime() est la suivante :

La syntaxe de la méthode DateTime::setTime()

$datetime->setTime($hour, $minute, $second, $microsecond);

Où :

• $datetime est l'objet DateTime à modifier.
• $hour est la nouvelle valeur des heures (0–23).
• $minute est la nouvelle valeur des minutes (0–59).
• $second est la nouvelle valeur des secondes (0–59, optionnel, 0 par défaut).
• $microsecond est la nouvelle valeur des microsecondes (0–999999, optionnel, 0 par défaut).

Remarque : Le fuseau horaire de l'objet DateTime est conservé lors de cette opération. La méthode modifie l'objet en place. Si les valeurs fournies dépassent leurs plages valides, PHP les normalise automatiquement (par exemple, une heure à 25 bascule sur le jour suivant) plutôt que de lever une exception.

Exemple d'utilisation

Voici un exemple illustrant l'utilisation de la méthode DateTime::setTime() :

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

Dans cet exemple, nous créons d'abord un nouvel objet DateTime avec la date et l'heure fixées à '2000-01-01 12:00:00'. Nous utilisons ensuite la méthode setTime() pour régler l'heure à 14 et les minutes à 30. Enfin, nous utilisons la méthode format() pour afficher la date et l'heure modifiées au format 'Y-m-d H:i:s'. Le résultat est :

2000-01-01 14:30:00

Comme nous n'avons pas passé $second ni $microsecond, les deux valent 0 par défaut, donc les secondes sont réinitialisées même si l'heure d'origine avait déjà :00 secondes.

Définir les secondes et les microsecondes

Vous pouvez passer les quatre arguments pour contrôler l'heure jusqu'à la microseconde. La composante microseconde n'apparaît dans la sortie que si votre chaîne de format inclut u :

<?php
$date = new DateTime('2000-01-01 12:00:00');
$date->setTime(14, 30, 15, 500000);
echo $date->format('Y-m-d H:i:s.u');

Cela affiche 2000-01-01 14:30:15.500000.

Les valeurs hors plage se propagent

setTime() ne lève pas d'exception pour des valeurs en dehors de la plage valide — elle les normalise et reporte le débordement sur la date. Fixer l'heure à 25 avance la date d'un jour :

<?php
$date = new DateTime('2000-01-01 23:30:00');
$date->setTime(25, 0);
echo $date->format('Y-m-d H:i:s');

Cela affiche 2000-01-02 01:00:00 — l'heure 25 devient 01:00 le jour suivant. C'est pratique pour les calculs arithmétiques (par exemple « ajouter 5 heures » en passant $hour + 5), mais cela peut introduire des bugs silencieux si vous attendiez une validation. Pour modifier directement la date, utilisez setDate(), ou modify() pour des décalages relatifs.

Comparaison de DateTime::setTime() avec d'autres fonctions

La méthode DateTime::setTime() est l'approche orientée objet standard en PHP pour modifier l'heure. Contrairement aux fonctions de date procédurales qui retournent de nouvelles chaînes ou nécessitent un parsing complexe, setTime() modifie directement l'objet DateTime en place, garantissant la sécurité des types et un comportement cohérent.

Cela contraste avec DateTimeImmutable::setTime(), qui retourne une nouvelle instance en laissant l'originale intacte :

<?php
$original = new DateTimeImmutable('2000-01-01 12:00:00');
$changed  = $original->setTime(8, 0);

echo $original->format('H:i'), ' | ', $changed->format('H:i');

Cela affiche 12:00 | 08:00 : $original est inchangé, et $changed contient la nouvelle heure. Avec le DateTime mutable, l'appel retourne le même objet modifié, donc $original et $changed pointeraient tous deux vers un objet 08:00. Préférez DateTimeImmutable lorsqu'une valeur est partagée ou transmise, afin d'éviter les mutations accidentelles.

Méthodes associées à utiliser conjointement avec setTime() : setDate() pour modifier l'année/le mois/le jour, setTimezone() pour convertir vers un autre fuseau horaire, et date_default_timezone_set() pour définir le fuseau horaire par défaut du script. Pour créer l'objet en premier lieu, consultez new DateTime.

Conclusion

La méthode DateTime::setTime() est un outil utile pour manipuler les dates et heures en PHP. En offrant un moyen simple de mettre à jour la partie heure d'un objet DateTime, elle propose une approche pratique et fiable pour la manipulation des dates et heures. Pour une gestion immuable des dates, utilisez DateTimeImmutable::setTime(), qui retourne une nouvelle instance au lieu de modifier l'originale.

Pratique