Fonction PHP date_timezone_get()

La fonction date_timezone_get() retourne le fuseau horaire attaché à un objet DateTime sous la forme d'un objet DateTimeZone. Savoir quel fuseau horaire un objet date porte fait toute la différence entre un horodatage signifiant « 15h à New York » et un autre signifiant « 15h quelque part d'indéfini » — et se tromper là-dessus est l'une des sources les plus courantes de bugs de décalage horaire dans les applications PHP.

Cette page couvre la signature de la fonction, ce qu'elle retourne (y compris en cas d'échec), l'équivalent orienté objet que vous rencontrerez plus souvent dans du code réel, ainsi que des exemples pratiques comme la lecture et la conversion d'un fuseau horaire.

Comprendre les fuseaux horaires en PHP

Un fuseau horaire est une région géographique partageant la même heure standard. Chacun est identifié par un nom IANA unique, tel que America/New_York ou Europe/London. PHP est livré avec la base de données IANA complète ; vous pouvez lister tous les noms pris en charge avec timezone_identifiers_list().

Chaque objet DateTime porte un fuseau horaire en interne. Si vous n'en spécifiez pas, il revient au fuseau horaire par défaut du script — la valeur définie par date_default_timezone_set() (ou, à défaut, la directive date.timezone dans php.ini). Pour modifier le fuseau horaire d'un objet existant plutôt que de le lire, utilisez date_timezone_set().

Point clé : date_timezone_get() ne convertit pas l'heure. Elle se contente de signaler l'étiquette de fuseau horaire actuellement attachée à l'objet. Pour déplacer réellement la valeur d'horloge murale vers une autre zone, vous devez changer le fuseau horaire avec setTimezone() / date_timezone_set().

La fonction date_timezone_get()

date_timezone_get() est l'alias procédural de la méthode DateTime::getTimezone(). Les deux font la même chose — retourner l'instance DateTimeZone détenue par un objet DateTime (ou DateTimeImmutable).

Syntaxe

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

L'équivalent orienté objet :

$object->getTimezone();

Paramètres

• $object : Un objet DateTime ou DateTimeImmutable dont on veut lire le fuseau horaire.

Valeur de retour

En cas de succès, retourne un objet DateTimeZone. Retourne false en cas d'échec (par exemple, si l'objet ne possède pas d'informations de fuseau horaire attachées). Appelez getName() sur le résultat pour obtenir la chaîne IANA telle que "Europe/London".

Exemples

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

Exemple 1 : Récupérer le fuseau horaire de la date et l'heure actuelles

Un objet DateTime créé sans fuseau horaire explicite hérite du fuseau horaire par défaut du script ; la sortie ici correspond donc à ce qui a été passé à date_default_timezone_set() — UTC dans cet exemple.

Exemple 2 : Récupérer le fuseau horaire après l'avoir modifié

Après que setTimezone() réassigne la zone, date_timezone_get() retourne la nouvelle valeur, America/New_York.

Exemple 3 : Lire le décalage et convertir entre des zones

Puisque date_timezone_get() retourne un objet DateTimeZone complet, vous pouvez le transmettre à d'autres appels conscients des fuseaux horaires — par exemple, pour lire le décalage UTC ou convertir un instant d'une zone à une autre :

<?php
// 9:00 AM in London on a summer date (BST, UTC+1)
$london = new DateTime('2023-07-01 09:00:00', new DateTimeZone('Europe/London'));

$tz = date_timezone_get($london);
echo $tz->getName(), "\n";                  // Europe/London
echo $tz->getOffset($london) / 3600, "\n";  // 1  (hours east of UTC)

// Convert the same instant to Tokyo time
$london->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i'), "\n";    // 2023-07-01 17:00

L'instant est identique ; seule la représentation de l'horloge murale change — 09h00 BST à Londres correspond à 17h00 JST à Tokyo. Consultez date_format() pour les caractères de formatage utilisés ci-dessus.

Pièges courants

• Elle lit, elle ne convertit pas. date_timezone_get() retourne uniquement la zone attachée. Réassigner le résultat à une autre variable ne changera pas la date — utilisez setTimezone() pour cela.
• Fuseau horaire par défaut vs. explicite. Un objet créé sans fuseau horaire hérite du fuseau par défaut du script. Si ce fuseau par défaut est incorrect, chaque lecture semble correcte, mais l'heure sous-jacente est décalée. Définissez-le une fois avec date_default_timezone_set().
• Privilégiez la forme POO dans le code moderne. $object->getTimezone() est le même appel et se lit plus naturellement dans les chaînes de méthodes.

Conclusion

date_timezone_get() retourne le DateTimeZone attaché à un objet DateTime, vous donnant le nom IANA ainsi que les outils pour lire les décalages ou convertir entre des zones. Combinée avec date_default_timezone_set() et date_timezone_set(), elle vous permet de maintenir des horodatages non ambigus pour les utilisateurs et serveurs situés dans différentes parties du monde.

Pratique