timezone_offset_get()

La función timezone_offset_get() en PHP devuelve el desplazamiento de zona horaria en segundos respecto al Tiempo Universal Coordinado (UTC) para un objeto DateTimeInterface dado. Esta guía cubre su sintaxis, parámetros y uso práctico.

Comprendiendo timezone_offset_get()

La función timezone_offset_get() devuelve el desplazamiento de la zona horaria en segundos respecto al Tiempo Universal Coordinado (UTC) para una fecha y hora específicas. Es una función integrada de PHP que permite a los desarrolladores manipular fechas y horas según zonas horarias concretas.

Sintaxis

La sintaxis de la función timezone_offset_get() en PHP es la siguiente:

Sintaxis de la función timezone_offset_get() en PHP

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

De forma procedimental, la función recibe un DateTimeZone y el DateTimeInterface para el que deseas obtener el desplazamiento, y devuelve el desplazamiento en segundos. La mayoría de los desarrolladores usan el equivalente orientado a objetos, DateTimeZone::getOffset(), que resulta más natural de leer:

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

Parámetros

La función timezone_offset_get() recibe dos parámetros:

1. $object - Un objeto DateTimeZone cuyo desplazamiento se desea leer.
2. $datetime - Un objeto DateTimeInterface (un DateTime o DateTimeImmutable) que representa el instante en el tiempo para el que se calcula el desplazamiento.

El instante importa: debido al horario de verano, la misma zona horaria puede tener un desplazamiento diferente en verano que en invierno, por lo que debes indicarle a la función qué momento concreto deseas.

Valor de retorno y notas

• Valor de retorno: Devuelve un entero con el desplazamiento en segundos. Es negativo para las zonas horarias al oeste de UTC (las Américas) y positivo para las del este.
• Versión de PHP: Disponible desde PHP 5.2.0.
• Manejo del horario de verano: El desplazamiento tiene en cuenta automáticamente el horario de verano. Para America/Los_Angeles, una fecha de invierno devuelve -28800 (UTC-8) mientras que una fecha de verano devuelve -25200 (UTC-7).
• Horas, no segundos: Para convertir el resultado en horas, divide entre 3600 (por ejemplo, -28800 / 3600 = -8).

Aplicaciones prácticas

La función timezone_offset_get() en PHP es una herramienta potente para trabajar con fechas y horas en zonas horarias específicas. Algunas aplicaciones prácticas de esta función incluyen:

1. Mostrar información de fecha y hora según la preferencia de zona horaria del usuario.
2. Convertir información de fecha y hora de una zona horaria a otra.
3. Realizar cálculos de fecha y hora con desplazamientos de zona horaria precisos.

Ejemplo de uso

A continuación se muestra un ejemplo de uso de la función timezone_offset_get() en PHP:

Ejemplo de la función timezone_offset_get() de PHP

La fecha de enero queda fuera del horario de verano, por lo que el desplazamiento es -28800 segundos (UTC-8):

-28800

El horario de verano en acción

Llamar a la misma zona horaria con una fecha de verano devuelve un desplazamiento diferente, ya que el horario de verano del Pacífico es UTC-7. Formatear el desplazamiento en horas facilita la lectura del resultado:

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

Conclusión

timezone_offset_get() (y su equivalente orientado a objetos DateTimeZone::getOffset()) te proporciona la distancia exacta de una zona horaria respecto a UTC en segundos para un momento específico, con el horario de verano ya considerado. Divide entre 3600 cuando necesites horas, y recuerda pasar la fecha que corresponde para que el horario de verano se resuelva correctamente.

Para profundizar más, consulta date_default_timezone_set() para establecer la zona horaria predeterminada del script, timezone_name_get() para leer el nombre de una zona horaria, y la lista completa de zonas horarias de PHP.

Práctica