timezone_offset_get()

La fonction timezone_offset_get() en PHP retourne le décalage horaire en secondes par rapport au Temps Universel Coordonné (UTC) pour un objet DateTimeInterface donné. Ce guide couvre sa syntaxe, ses paramètres et son utilisation pratique.

Comprendre timezone_offset_get()

La fonction timezone_offset_get() retourne le décalage du fuseau horaire en secondes par rapport au Temps Universel Coordonné (UTC) pour une date et une heure spécifiées. C'est une fonction PHP intégrée qui permet aux développeurs de manipuler les dates et les heures selon des fuseaux horaires spécifiques.

Syntaxe

La syntaxe de la fonction timezone_offset_get() en PHP est la suivante :

La syntaxe de la fonction timezone_offset_get() en PHP

<?php
timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

De façon procédurale, la fonction prend un DateTimeZone et le DateTimeInterface pour lequel vous souhaitez le décalage, et retourne ce décalage en secondes. La plupart des développeurs utilisent l'équivalent orienté objet, DateTimeZone::getOffset(), qui se lit plus naturellement :

<?php
$tz   = new DateTimeZone('America/Los_Angeles');
$date = new DateTime('2019-01-01 12:00:00', $tz);

// These two calls are equivalent:
$offset = timezone_offset_get($tz, $date);
$offset = $tz->getOffset($date);

Paramètres

La fonction timezone_offset_get() prend deux paramètres :

1. $object - Un objet DateTimeZone dont vous souhaitez lire le décalage.
2. $datetime - Un objet DateTimeInterface (un DateTime ou DateTimeImmutable) représentant le moment dans le temps pour lequel le décalage est calculé.

Le moment est important : en raison de l'heure d'été, le même fuseau horaire peut avoir un décalage différent en été et en hiver, vous devez donc indiquer à la fonction quel instant vous visez.

Valeur de retour et remarques

• Valeur de retour : Retourne un décalage entier en secondes. Il est négatif pour les fuseaux horaires à l'ouest d'UTC (les Amériques) et positif pour ceux à l'est.
• Version PHP : Disponible depuis PHP 5.2.0.
• Gestion de l'heure d'été : Le décalage tient automatiquement compte de l'heure d'été. Pour America/Los_Angeles, une date hivernale retourne -28800 (UTC-8) tandis qu'une date estivale retourne -25200 (UTC-7).
• Heures, pas secondes : Pour convertir le résultat en heures, divisez par 3600 (ex. -28800 / 3600 = -8).

Applications pratiques

La fonction timezone_offset_get() en PHP est un outil puissant pour travailler avec des dates et des heures dans des fuseaux horaires spécifiques. Voici quelques applications pratiques de cette fonction :

1. Afficher des informations de date et d'heure selon les préférences de fuseau horaire de l'utilisateur.
2. Convertir des informations de date et d'heure d'un fuseau horaire à un autre.
3. Effectuer des calculs de date et d'heure avec des décalages de fuseau horaire précis.

Exemple d'utilisation

Voici un exemple d'utilisation de la fonction timezone_offset_get() en PHP :

Exemple de la fonction PHP timezone_offset_get()

La date de janvier est en dehors de l'heure d'été, donc le décalage est de -28800 secondes (UTC-8) :

-28800

L'heure d'été en action

Appeler le même fuseau horaire avec une date estivale retourne un décalage différent, car l'heure d'été du Pacifique est UTC-7. Formater le décalage en heures rend le résultat facile à lire :

<?php
$tz = new DateTimeZone('America/Los_Angeles');

foreach (['2019-01-01 12:00:00', '2019-07-01 12:00:00'] as $when) {
    $date    = new DateTime($when, $tz);
    $seconds = $tz->getOffset($date);
    $hours   = $seconds / 3600;
    echo "$when => $seconds seconds (UTC$hours)\n";
}

2019-01-01 12:00:00 => -28800 seconds (UTC-8)
2019-07-01 12:00:00 => -25200 seconds (UTC-7)

Conclusion

timezone_offset_get() (et son équivalent orienté objet DateTimeZone::getOffset()) vous donne la distance exacte d'un fuseau horaire par rapport à UTC en secondes pour un moment spécifique, avec l'heure d'été déjà prise en compte. Divisez par 3600 lorsque vous avez besoin d'heures, et n'oubliez pas de passer la date qui vous intéresse afin que l'heure d'été soit correctement résolue.

Pour aller plus loin, consultez date_default_timezone_set() pour définir le fuseau horaire par défaut du script, timezone_name_get() pour lire le nom d'un fuseau horaire, et la liste complète des fuseaux horaires PHP.

Pratique