Función PHP date_timezone_get()

La función date_timezone_get() devuelve la zona horaria asociada a un objeto DateTime como un objeto DateTimeZone. Saber qué zona horaria lleva una fecha marca la diferencia entre una marca de tiempo que significa "3 PM en Nueva York" y una que significa "3 PM en algún lugar indefinido" — y equivocarse en esto es una de las fuentes más comunes de errores de desfase horario en aplicaciones PHP.

Esta página cubre la firma de la función, lo que devuelve (incluso en caso de fallo), el equivalente orientado a objetos que verás con más frecuencia en código real, y ejemplos prácticos como leer y convertir una zona horaria.

Comprensión de las zonas horarias en PHP

Una zona horaria es una región geográfica que comparte la misma hora estándar. Cada una se identifica con un nombre IANA único, como America/New_York o Europe/London. PHP incluye la base de datos IANA completa; puedes listar todos los nombres admitidos con timezone_identifiers_list().

Cada objeto DateTime lleva internamente una zona horaria. Si no especificas una, hereda la zona horaria predeterminada del script — el valor establecido por date_default_timezone_set() (o, en su defecto, la directiva date.timezone en php.ini). Para cambiar la zona horaria de un objeto existente en lugar de leerla, usa date_timezone_set().

Un punto clave: date_timezone_get() no convierte la hora. Solo informa la etiqueta de zona horaria actualmente asociada al objeto. Para desplazar realmente el valor del reloj a otra zona, cambia la zona horaria con setTimezone() / date_timezone_set().

La función date_timezone_get()

date_timezone_get() es el alias procedimental del método DateTime::getTimezone(). Ambos hacen lo mismo: devuelven la instancia DateTimeZone que contiene un objeto DateTime (o DateTimeImmutable).

Sintaxis

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

El equivalente orientado a objetos:

$object->getTimezone();

Parámetros

• $object: Un objeto DateTime o DateTimeImmutable del que leer la zona horaria.

Valor de retorno

En caso de éxito devuelve un objeto DateTimeZone. Devuelve false en caso de fallo (por ejemplo, si el objeto no tiene información de zona horaria asociada). Llama a getName() sobre el resultado para obtener la cadena IANA, como "Europe/London".

Ejemplos

A continuación se muestran algunos ejemplos de cómo se puede usar la función date_timezone_get():

Ejemplo 1: Obtener la zona horaria de la fecha y hora actuales

Un DateTime creado sin una zona horaria explícita hereda el valor predeterminado del script, por lo que la salida aquí es lo que se pasó a date_default_timezone_set() — UTC en este ejemplo.

Ejemplo 2: Obtener la zona horaria después de cambiarla

Después de que setTimezone() reasigna la zona, date_timezone_get() informa el nuevo valor, America/New_York.

Ejemplo 3: Leer el desplazamiento y convertir entre zonas

Como date_timezone_get() devuelve un objeto DateTimeZone completo, puedes pasarlo a otras llamadas que admiten zonas horarias — por ejemplo, para leer el desplazamiento UTC o convertir un instante de una zona a otra:

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

El instante es idéntico; solo cambia la representación del reloj — las 09:00 BST de Londres son las 17:00 JST de Tokio. Consulta date_format() para los caracteres de formato utilizados arriba.

Errores comunes

• Solo lee, no convierte. date_timezone_get() únicamente devuelve la zona asociada. Reasignar el resultado a otra variable no cambia la fecha — usa setTimezone() para eso.
• Zona predeterminada frente a zona explícita. Un objeto construido sin zona horaria hereda el valor predeterminado del script. Si ese valor es incorrecto, cada lectura parece correcta pero la hora subyacente está desajustada. Establécela una vez con date_default_timezone_set().
• Prefiere la forma OOP en código moderno. $object->getTimezone() es la misma llamada y se lee de forma más natural dentro de cadenas de métodos.

Conclusión

date_timezone_get() devuelve el DateTimeZone asociado a un objeto DateTime, proporcionándote el nombre IANA y las herramientas para leer desplazamientos o convertir entre zonas. Combinado con date_default_timezone_set() y date_timezone_set(), te permite mantener las marcas de tiempo sin ambigüedad para usuarios y servidores en distintas partes del mundo.

Práctica