date_timezone_set()

Introduction

date_timezone_set() change le fuseau horaire d'un objet DateTime existant. Point essentiel : elle ne modifie pas l'instant absolu dans le temps — elle change la représentation affichée de cet instant. Le même moment est simplement ré-exprimé dans un autre fuseau horaire, de sorte que les heures et les minutes affichées changent tandis que le point absolu sur la ligne du temps reste identique.

C'est donc le bon outil lorsque vous disposez d'une date/heure dans un fuseau et que vous devez l'afficher dans un autre : convertir un horodatage UTC stocké vers l'heure locale d'un utilisateur, ou comparer des événements enregistrés dans différentes régions.

date_timezone_set() est l'alias procédural de la méthode DateTime::setTimezone() — les deux font exactement la même chose.

Syntaxe

date_timezone_set(DateTime $object, DateTimeZone $timezone): DateTime|false

• $object — l'objet DateTime dont vous souhaitez changer le fuseau horaire.
• $timezone — un objet DateTimeZone contenant le fuseau cible (par exemple new DateTimeZone('Asia/Tokyo')).

La fonction modifie $object en place et retourne la même instance en cas de succès (pratique pour le chaînage), ou false en cas d'échec. Comme elle modifie l'objet d'origine, il n'y a pas de « copie » séparée — c'est l'objet d'entrée lui-même qui change.

Exemple de base

2023-03-03 21:00:00

L'objet commence à 12:00 à Londres (Europe/London, soit UTC+0 en mars). Tokyo est 9 heures en avance, donc le même instant s'affiche 21:00. Rien dans le moment réel n'a changé — seul le fuseau dans lequel il est présenté a évolué.

L'instant reste le même — seul l'affichage change

C'est la chose la plus importante à comprendre à propos de date_timezone_set(). Comparez la valeur avant et après la conversion :

<?php
$date = new DateTime('2023-03-03 12:00:00', new DateTimeZone('Europe/London'));
echo $date->format('Y-m-d H:i:s P'), "\n";   // before

date_timezone_set($date, new DateTimeZone('Asia/Tokyo'));
echo $date->format('Y-m-d H:i:s P'), "\n";   // after

2023-03-03 12:00:00 +00:00
2023-03-03 21:00:00 +09:00

L'heure affichée et le décalage UTC changent tous les deux, mais 12:00 +00:00 et 21:00 +09:00 représentent le même point dans le temps. Si vous n'avez besoin que de l'instant absolu (par exemple un horodatage UNIX), celui-ci sera inchangé.

Si vous souhaitez au contraire remplacer l'heure affichée sans la convertir, n'utilisez pas cette fonction — définissez l'heure directement avec date_time_set().

L'heure d'été est gérée automatiquement

Parce que la conversion passe par un vrai DateTimeZone, les règles d'heure d'été (DST) sont appliquées automatiquement. New York est UTC-5 en hiver mais UTC-4 en été, et date_timezone_set() choisit le bon décalage pour la date en question :

<?php
$utc = new DateTime('2023-06-21 12:00:00', new DateTimeZone('UTC'));
date_timezone_set($utc, new DateTimeZone('America/New_York'));
echo $utc->format('Y-m-d H:i:s');

2023-06-21 08:00:00

En juin, New York est à l'heure d'été de l'Est (UTC-4), donc 12:00 UTC devient 08:00. Exécutez le même code avec une date de janvier et vous obtiendriez 07:00 (UTC-5) à la place — sans aucun changement dans votre code. C'est pourquoi vous devriez toujours utiliser des identifiants de zone IANA comme America/New_York plutôt que des décalages fixes comme -05:00.

Style procédural vs. orienté objet

date_timezone_set($obj, $tz) et $obj->setTimezone($tz) sont interchangeables. La forme méthode se lit généralement mieux et se chaîne naturellement :

<?php
$london = (new DateTime('2023-03-03 12:00:00', new DateTimeZone('Europe/London')))
    ->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i:s');

2023-03-03 21:00:00

Cas d'utilisation courants

• Afficher des heures UTC stockées dans le fuseau d'un utilisateur. Stockez chaque horodatage en UTC, puis convertissez à l'affichage avec date_timezone_set() selon le fuseau préféré de chaque utilisateur.
• Normaliser des heures provenant de plusieurs régions avant de les comparer ou de les trier.
• Construire des rapports régionalisés, en affichant le même événement dans plusieurs fuseaux côte à côte.

Points de vigilance

• La fonction modifie l'objet d'origine. Si vous avez besoin de conserver la valeur source, clonez-la d'abord : $copy = clone $date; puis convertissez $copy.
• Elle ne parse pas et ne définit pas une nouvelle date — elle se contente de re-projeter l'instant existant. Utilisez date_create() pour construire un DateTime et date_time_set() pour écraser l'heure.
• Pour lire le fuseau actuellement attaché à un objet, utilisez date_timezone_get().
• Ne la confondez pas avec date_default_timezone_set(), qui définit le fuseau par défaut à l'échelle du script pour toutes les fonctions de date/heure — un rôle complètement différent.

Diagramme

graph LR
A[DateTime Object] --> B((date_timezone_set))
C[Target DateTimeZone] --> B
B --> D[Same instant, new wall-clock display]

Exercice pratique