date_default_timezone_set()

Introducción

La función date_default_timezone_set() establece la zona horaria predeterminada utilizada por todas las funciones de fecha/hora en un script PHP. Una vez que la llamas, funciones como date(), mktime(), strtotime() y DateTime interpretan y formatean las horas en relación con esa zona horaria. Esta página explica qué hace la función, cuándo la necesitas y las trampas que debes evitar.

Sintaxis

date_default_timezone_set(string $timezoneId): bool

$timezoneId es una cadena identificadora de zona horaria de la base de datos IANA, como Europe/London o Asia/Tokyo — no una abreviatura como EST. La función devuelve true si tiene éxito y false si el identificador no es válido. Cuando el identificador no es válido, PHP también emite un E_WARNING y vuelve a la zona horaria configurada anteriormente.

Por qué importa

Una marca de tiempo es simplemente un número de segundos desde la época Unix (UTC). Para convertir ese número en una fecha legible — "2024-03-15 14:30" — PHP necesita saber en qué zona horaria representarla. Si no estableces una, PHP usa el valor date.timezone de php.ini, que puede diferir entre tu máquina local, el entorno de pruebas y producción. Esa discrepancia es la fuente clásica del error "la hora está desfasada unas horas".

Llamar a date_default_timezone_set() al principio de tu script hace que la zona horaria sea explícita y coherente en todos los entornos donde se ejecute tu código, independientemente de cómo esté configurado el servidor.

Uso básico

<?php
date_default_timezone_set('America/New_York');

echo date('Y-m-d H:i:s');

Esto establece la zona horaria del script en la hora del Este de EE. UU. Todas las llamadas de fecha/hora posteriores se representarán en esa zona. Establecer la zona no cambia la marca de tiempo subyacente, solo la forma en que se muestra.

Cambiar zonas horarias en tiempo de ejecución

Puedes cambiar la zona horaria predeterminada más de una vez. La misma marca de tiempo Unix muestra una hora de reloj diferente en cada zona:

Aquí date_default_timezone_get() confirma la zona que está en efecto actualmente — útil al depurar.

Manejar un identificador no válido

Dado que la función devuelve false (y emite una advertencia) con un identificador incorrecto, valida el valor de retorno cuando la zona provenga de la entrada del usuario o de configuración:

<?php
$zone = 'Mars/Olympus_Mons'; // not a real timezone

if (@date_default_timezone_set($zone)) {
    echo "Timezone set to $zone\n";
} else {
    date_default_timezone_set('UTC');
    echo "Invalid timezone, falling back to UTC\n";
}
// Outputs: Invalid timezone, falling back to UTC

Identificadores de uso frecuente

PHP admite cientos de zonas. Algunos de los más utilizados:

Para obtener la lista completa generada automáticamente, usa timezone_identifiers_list() y consulta la referencia de zonas horarias de PHP para una visión general.

Buenas prácticas

• Establécela una sola vez, al principio. Llámala cerca del inicio de tu archivo de arranque/entrada para que toda la solicitud comparta una misma zona.
• Prefiere almacenar en UTC. Guarda las marcas de tiempo en UTC en la base de datos y conviértelas a la zona del usuario solo para mostrarlas; esto evita ambigüedades con el horario de verano.
• Usa identificadores, no abreviaturas. Europe/London tiene en cuenta el cambio de hora automáticamente; GMT/BST no lo hacen.

Conclusión

date_default_timezone_set() te brinda control explícito sobre cómo PHP representa las fechas y horas, manteniendo un comportamiento coherente entre entornos. Establécela deliberadamente, valida los identificadores no confiables y confirma la zona activa con date_default_timezone_get() cuando algo parezca incorrecto.

Práctica