timezone_name_get()

Introduction

Cet article couvre la fonction timezone_name_get en PHP. Nous en explorerons la syntaxe, les paramètres et les valeurs de retour, ainsi que des exemples concrets. Cette fonction lit l'identifiant d'un objet DateTimeZone, ce qui est pratique lorsque vous stockez un objet de fuseau horaire et avez ensuite besoin de son nom pour la journalisation, l'affichage ou la comparaison.

timezone_name_get est l'alias procédural de la méthode DateTimeZone::getName. Les deux sont interchangeables ; utilisez celui qui correspond le mieux à votre style de code.

Disponibilité : timezone_name_get fait partie de l'extension date/heure intégrée de PHP. Elle est toujours disponible — aucune extension supplémentaire (comme intl) n'est nécessaire.

Syntaxe

La fonction timezone_name_get prend un seul objet DateTimeZone et retourne le nom du fuseau horaire qu'il représente. Voici la signature :

Syntaxe de la fonction PHP timezone_name_get()

timezone_name_get(DateTimeZone $object): string

Décomposons les paramètres :

• $object : Il s'agit d'un objet DateTimeZone qui représente un fuseau horaire.

Paramètres

Comme mentionné ci-dessus, la fonction timezone_name_get ne prend qu'un seul paramètre : un objet DateTimeZone. Cet objet représente un fuseau horaire spécifique et est créé à l'aide de la classe DateTimeZone. Voici un exemple de création d'un objet DateTimeZone :

Exemple de création d'un objet DateTimeZone en PHP

<?php

$timezone = new DateTimeZone('America/New_York');

Dans cet exemple, nous créons un objet DateTimeZone représentant le fuseau horaire Eastern Time aux États-Unis.

Remarque : En PHP 8+, la vérification stricte des types est appliquée. Passer un argument qui n'est pas un objet DateTimeZone lèvera une TypeError.

Valeurs de retour

La fonction timezone_name_get retourne une string représentant le nom du fuseau horaire représenté par l'objet DateTimeZone passé en paramètre. Voici un exemple de son utilisation :

Exemple d'utilisation de la fonction timezone_name_get() en PHP

Dans cet exemple, nous créons un objet DateTimeZone représentant le fuseau horaire Eastern Time, puis nous le passons à la fonction timezone_name_get. La fonction retourne alors la string "America/New_York", que nous affichons avec l'instruction echo.

La fonction renvoie toujours l'identifiant canonique avec lequel l'objet a été construit. Si vous créez l'objet à partir d'un décalage ou d'une abréviation, le nom retourné le reflète :

Noms pour les zones basées sur un décalage et une abréviation

<?php

echo timezone_name_get(new DateTimeZone('+05:00')), PHP_EOL; // Output: +05:00
echo timezone_name_get(new DateTimeZone('GMT')), PHP_EOL;    // Output: GMT
echo timezone_name_get(new DateTimeZone('UTC')), PHP_EOL;    // Output: UTC

Pour les zones nommées, le résultat est la même string que vous pouvez passer à des fonctions comme date_default_timezone_set, ce qui en fait un identifiant d'aller-retour fiable.

Exemples concrets

Maintenant que nous avons couvert les bases de la fonction timezone_name_get, explorons quelques exemples concrets de son utilisation.

Exemple 1 : Afficher les fuseaux horaires dans un menu déroulant

Supposons que nous voulions créer un formulaire permettant aux utilisateurs de sélectionner leur fuseau horaire. Nous pouvons utiliser la classe DateTimeZone ainsi que la fonction timezone_name_get pour remplir un menu déroulant avec tous les fuseaux horaires disponibles. Voici un exemple :

Afficher les fuseaux horaires dans un menu déroulant en PHP

<select name="timezone">
  <?php foreach(DateTimeZone::listIdentifiers() as $timezone): ?>
    <option value="<?php echo $timezone; ?>">
      <?php echo $timezone; ?>
    </option>
  <?php endforeach; ?>
</select>

Dans cet exemple, nous utilisons la méthode listIdentifiers de la classe DateTimeZone pour obtenir la liste de tous les fuseaux horaires disponibles. Puisque listIdentifiers retourne déjà les noms canoniques des fuseaux horaires, nous pouvons directement utiliser $timezone pour la valeur et le libellé, rendant le code plus efficace.

Exemple 2 : Convertir une date vers un autre fuseau horaire

Supposons que nous ayons une date en fuseau horaire Pacific Time et que nous voulions la convertir en Eastern Time. Nous pouvons utiliser la classe DateTime avec les fonctions DateTimeZone et timezone_name_get pour y parvenir. Voici un exemple :

Conversion d'une date vers un autre fuseau horaire en PHP

Dans cet exemple, nous créons un objet DateTime représentant une date et une heure en Pacific Time, en utilisant l'identifiant de fuseau horaire America/Los_Angeles. Nous créons ensuite un clone de cet objet et utilisons la méthode setTimezone pour le convertir en Eastern Time, avec l'identifiant America/New_York. Enfin, nous affichons les dates dans les deux fuseaux horaires à l'aide de la méthode format, et vérifions les noms de fuseaux horaires actifs avec timezone_name_get.

Notez que l'heure Eastern affiche 12:00:00 contre 09:00:00 pour le Pacific — trois heures d'avance, exactement comme prévu.

Alternative orientée objet

Puisque timezone_name_get n'est qu'un wrapper autour de DateTimeZone::getName, vous pouvez appeler la méthode directement :

Style procédural vs. orienté objet

<?php

$timezone = new DateTimeZone('Europe/Berlin');

echo timezone_name_get($timezone), PHP_EOL; // Procedural
echo $timezone->getName(), PHP_EOL;          // Object-oriented
// Both output: Europe/Berlin

Les deux formes retournent la même string. La méthode orientée objet se chaîne facilement lorsque vous disposez déjà d'une instance DateTimeZone.

Fonctions associées

• timezone_open — créer un objet DateTimeZone dont vous pourrez lire le nom ultérieurement.
• date_timezone_get — obtenir le DateTimeZone attaché à un objet DateTime.
• timezone_offset_get — obtenir le décalage d'une zone (en secondes) par rapport à UTC pour un moment donné.
• timezone_identifiers_list — lister tous les identifiants de fuseaux horaires valides.

Pour une vue d'ensemble plus large, consultez le chapitre PHP Timezones.

Conclusion

Cet article a couvert la fonction timezone_name_get en PHP, notamment sa syntaxe, ses paramètres, ses valeurs de retour et ses cas d'utilisation pratiques. Elle retourne l'identifiant canonique stocké dans un objet DateTimeZone, est disponible sans extension supplémentaire et reflète la méthode DateTimeZone::getName. Nous espérons que ces informations vous aideront à gérer les conversions de fuseaux horaires de manière plus fiable dans vos projets.

Pratique