timezone_name_get()

Introducción

Este artículo cubre la función timezone_name_get en PHP. Exploraremos su sintaxis, parámetros y valores de retorno, junto con ejemplos del mundo real. Esta función lee el identificador de un objeto DateTimeZone, lo cual resulta útil cuando almacenas un objeto de zona horaria y necesitas su nombre posteriormente para registro, visualización o comparación.

timezone_name_get es el alias procedimental del método DateTimeZone::getName. Ambos son intercambiables, así que utiliza el estilo que mejor se adapte a tu código.

Disponibilidad: timezone_name_get forma parte de la extensión de fecha/hora integrada de PHP. Siempre está disponible — no es necesario instalar ninguna extensión adicional (como intl).

Sintaxis

La función timezone_name_get recibe un único objeto DateTimeZone y devuelve el nombre de la zona horaria que representa. Esta es la firma:

La sintaxis de la función PHP timezone_name_get()

timezone_name_get(DateTimeZone $object): string

Analicemos los parámetros:

• $object: Es un objeto DateTimeZone que representa una zona horaria.

Parámetros

Como se mencionó anteriormente, la función timezone_name_get recibe un único parámetro: un objeto DateTimeZone. Este objeto representa una zona horaria específica y se crea utilizando la clase DateTimeZone. A continuación se muestra un ejemplo de cómo crear un objeto DateTimeZone:

Ejemplo de creación de un objeto DateTimeZone en PHP

<?php

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

En este ejemplo, creamos un objeto DateTimeZone que representa la Zona Horaria del Este de los Estados Unidos.

Nota: En PHP 8+, se aplica la verificación estricta de tipos. Pasar un argumento que no sea un objeto DateTimeZone lanzará un TypeError.

Valores de retorno

La función timezone_name_get devuelve un string que representa el nombre de la zona horaria representada por el objeto DateTimeZone pasado como parámetro. A continuación se muestra un ejemplo de cómo se puede utilizar:

Ejemplo de uso de la función timezone_name_get() en PHP

En este ejemplo, creamos un objeto DateTimeZone que representa la Zona Horaria del Este y lo pasamos a la función timezone_name_get. La función devuelve el string "America/New_York", que mostramos usando la sentencia echo.

La función siempre devuelve el identificador canónico con el que se construyó el objeto. Si creas el objeto desde un desplazamiento o una abreviatura, el nombre devuelto lo refleja:

Nombres para zonas basadas en desplazamiento y abreviatura

<?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

Para zonas con nombre, el resultado es el mismo string que puedes pasar a funciones como date_default_timezone_set, lo que lo convierte en un identificador de ida y vuelta seguro.

Ejemplos del mundo real

Ahora que hemos cubierto los conceptos básicos de la función timezone_name_get, exploremos algunos ejemplos del mundo real sobre cómo puede utilizarse.

Ejemplo 1: Mostrar zonas horarias en un menú desplegable

Supongamos que queremos crear un formulario que permita a los usuarios seleccionar su zona horaria. Podemos usar la clase DateTimeZone junto con la función timezone_name_get para rellenar un menú desplegable con todas las zonas horarias disponibles. A continuación se muestra un ejemplo:

Mostrar zonas horarias en un menú desplegable en PHP

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

En este ejemplo, utilizamos el método listIdentifiers de la clase DateTimeZone para obtener una lista de todas las zonas horarias disponibles. Dado que listIdentifiers ya devuelve los nombres canónicos de las zonas horarias, podemos usar directamente $timezone tanto para el valor como para la etiqueta, lo que hace el código más eficiente.

Ejemplo 2: Convertir una fecha a otra zona horaria

Supongamos que tenemos una fecha en la Zona Horaria del Pacífico y queremos convertirla a la Zona Horaria del Este. Podemos usar la clase DateTime junto con DateTimeZone y la función timezone_name_get para lograrlo. A continuación se muestra un ejemplo:

Convertir una fecha a otra zona horaria en PHP

En este ejemplo, creamos un objeto DateTime que representa una fecha y hora en la Zona Horaria del Pacífico, utilizando el identificador de zona horaria America/Los_Angeles. Luego creamos un clon de este objeto y usamos el método setTimezone para convertirlo a la Zona Horaria del Este, usando el identificador America/New_York. Finalmente, mostramos las fechas en ambas zonas horarias usando el método format y verificamos los nombres de zona horaria activos con timezone_name_get.

Obsérvese que la hora del Este muestra 12:00:00 frente a 09:00:00 del Pacífico — tres horas de diferencia, exactamente como se esperaba.

Alternativa orientada a objetos

Dado que timezone_name_get es solo un envoltorio alrededor de DateTimeZone::getName, puedes llamar al método directamente:

Estilo procedimental vs. orientado a objetos

<?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

Ambas formas devuelven el mismo string. El método orientado a objetos se encadena de forma elegante cuando ya tienes una instancia de DateTimeZone.

Funciones relacionadas

• timezone_open — crea un objeto DateTimeZone cuyo nombre podrás leer posteriormente.
• date_timezone_get — obtiene el DateTimeZone asociado a un objeto DateTime.
• timezone_offset_get — obtiene el desplazamiento de una zona (en segundos) respecto a UTC para un momento dado.
• timezone_identifiers_list — lista todos los identificadores de zona horaria válidos.

Para una visión general más amplia, consulta el capítulo PHP Timezones.

Conclusión

Este artículo ha cubierto la función timezone_name_get en PHP, incluyendo su sintaxis, parámetros, valores de retorno y casos de uso prácticos. Devuelve el identificador canónico almacenado en un objeto DateTimeZone, está disponible sin ninguna extensión adicional y es equivalente al método DateTimeZone::getName. Esperamos que estos conocimientos te ayuden a manejar las conversiones de zona horaria de forma más fiable en tus proyectos.

Práctica