date_timestamp_set()

La fonction PHP date_timestamp_set()

date_timestamp_set() définit la date et l'heure d'un objet DateTime à partir d'un horodatage Unix — le nombre de secondes écoulées depuis le 1er janvier 1970, 00:00:00 UTC (l'« époque Unix »). Elle écrase la date que l'objet contenait auparavant et le fixe à l'instant exact que représente l'horodatage.

Cette page couvre la syntaxe de la fonction, un exemple concret, son interaction avec les fuseaux horaires (le point où la plupart des gens se trompent), l'équivalent orienté objet DateTime::setTimestamp(), les cas d'utilisation courants, et ses liens avec d'autres fonctions de date PHP.

Syntaxe

date_timestamp_set(DateTime $object, int $timestamp): DateTime

• $object — une instance DateTime à modifier.
• $timestamp — un horodatage Unix (secondes depuis l'époque). Passez un nombre négatif pour les dates antérieures à 1970.
• Retourne — le même objet DateTime (les appels peuvent donc être chaînés), désormais mis à jour.

Étant donné qu'elle modifie et retourne l'objet passé en paramètre, date_timestamp_set() est l'équivalent procédural de la méthode DateTime::setTimestamp() — les deux font la même chose.

Un exemple de base

Ce code définit un objet DateTime au 1er janvier 2022, 00:00:00 UTC, dont l'horodatage Unix est 1640995200 :

Nous créons un objet DateTime, le passons à date_timestamp_set() avec l'horodatage, puis nous format() le résultat. La date initiale produite par le constructeur (le moment actuel) est ignorée.

Un horodatage Unix pointe toujours vers un moment en UTC — il ne contient pas de fuseau horaire propre. Si vous avez besoin de l'horodatage pour une date calendaire donnée, utilisez mktime(), strtotime(), ou (new DateTime('2022-01-01'))->getTimestamp().

Les horodatages sont absolus — le fuseau horaire n'affecte que l'affichage

Une idée reçue courante est que date_timestamp_set() « convertit » une date entre fuseaux horaires. Elle ne change pas quel instant l'objet représente ; elle se contente de définir cet instant. Ce qui change selon les fuseaux horaires, c'est la façon dont format() affiche cet instant.

Le même horodatage affiché dans deux fuseaux horaires différents :

<?php
$timestamp = 1640995200; // 2022-01-01 00:00:00 UTC

$nyc = new DateTime('now', new DateTimeZone('America/New_York'));
date_timestamp_set($nyc, $timestamp);

echo $nyc->format('Y-m-d H:i:s P'); // 2021-12-31 19:00:00 -05:00

L'instant est identique, mais New York est cinq heures en retard sur UTC en janvier, donc l'heure affichée est le soir du 31 décembre. Appeler $nyc->getTimestamp() retourne toujours 1640995200. Pour vraiment changer le fuseau horaire affiché, définissez-le explicitement avec date_timezone_set().

Équivalent orienté objet

Si vous préférez le chaînage de méthodes, DateTime::setTimestamp() est identique dans ses effets :

<?php
date_default_timezone_set('UTC');

$date = (new DateTime())->setTimestamp(1640995200);

echo $date->format('Y-m-d H:i:s'); // 2022-01-01 00:00:00

Les deux styles modifient l'objet en place et le retournent, alors choisissez celui qui se lit le mieux dans votre code.

Cas d'utilisation courants

• Restaurer une heure stockée. Les bases de données et les API stockent souvent les heures sous forme d'horodatages Unix entiers. date_timestamp_set() reconstruit un DateTime à partir de cet entier pour pouvoir le formater ou effectuer des calculs avec date_add() et date_diff().
• Normaliser les entrées utilisateur. Convertissez les dates saisies par l'utilisateur en horodatage avec strtotime(), puis initialisez un DateTime à partir de cette valeur canonique unique.
• Réinitialiser un objet existant. Lorsque vous disposez déjà d'un DateTime configuré (avec un fuseau horaire choisi ou un workflow de formatage) et que vous souhaitez simplement le pointer vers un nouvel instant sans le reconstruire.

Fonctions associées

• date_timestamp_get() — l'inverse : lire l'horodatage Unix d'un DateTime.
• date_date_set() et date_time_set() — définir la date ou l'heure par composant au lieu d'un horodatage.
• date_default_timezone_set() — contrôler le fuseau horaire utilisé quand aucun DateTimeZone n'est fourni.

Conclusion

date_timestamp_set() définit un objet DateTime à l'instant exact décrit par un horodatage Unix, en écrasant sa valeur précédente et en retournant le même objet. N'oubliez pas que l'horodatage est toujours basé sur UTC et que le fuseau horaire ne change que la façon dont le résultat est affiché — pas l'instant qu'il représente. Pour l'opération inverse, utilisez date_timestamp_get().

Pratique