date_default_timezone_set()

Introdução

A função date_default_timezone_set() define o fuso horário padrão usado por todas as funções de data/hora em um script PHP. Após chamá-la, funções como date(), mktime(), strtotime() e DateTime interpretam e formatam os horários em relação a esse fuso. Esta página explica o que a função faz, quando você precisa dela e as armadilhas a serem evitadas.

Sintaxe

date_default_timezone_set(string $timezoneId): bool

$timezoneId é uma string identificadora de fuso horário do banco de dados IANA, como Europe/London ou Asia/Tokyo — não uma abreviação como EST. A função retorna true em caso de sucesso e false se o identificador for inválido. Quando o identificador é inválido, o PHP também emite um E_WARNING e retorna ao fuso horário configurado anteriormente.

Por que isso importa

Um timestamp é apenas um número de segundos desde a época Unix (UTC). Para transformar esse número em uma data legível — "2024-03-15 14:30" — o PHP precisa saber em qual fuso horário renderizá-la. Se você não definir um, o PHP usa o valor date.timezone do php.ini, que pode diferir entre sua máquina local, ambiente de staging e produção. Essa diferença é uma fonte clássica de bugs do tipo "o horário está errado por algumas horas".

Chamar date_default_timezone_set() logo no início do seu script torna o fuso horário explícito e consistente em todos os lugares onde seu código é executado, independentemente de como o servidor estiver configurado.

Uso básico

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

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

Isso define o fuso horário do script como Horário do Leste dos EUA. Cada chamada subsequente de data/hora agora é renderizada nesse fuso. Definir o fuso não altera o timestamp subjacente — apenas como ele é exibido.

Alternando fusos horários em tempo de execução

Você pode alterar o fuso horário padrão mais de uma vez. O mesmo timestamp Unix mostra um horário de relógio diferente em cada fuso:

Aqui date_default_timezone_get() confirma o fuso atualmente em vigor — útil na depuração.

Lidando com um identificador inválido

Como a função retorna false (e emite um aviso) com um identificador inválido, valide o valor de retorno quando o fuso vier de entrada do usuário ou de configuração:

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

O PHP suporta centenas de fusos. Alguns dos mais frequentemente utilizados:

Para a lista completa gerada automaticamente, use timezone_identifiers_list() e consulte a referência de fusos horários do PHP para uma visão geral.

Boas práticas

• Defina uma vez, logo no início. Chame a função perto do topo do seu arquivo de bootstrap/entrada para que toda a requisição compartilhe um único fuso.
• Prefira armazenar em UTC. Salve os timestamps em UTC no banco de dados e converta para o fuso do usuário somente na exibição; isso evita ambiguidades relacionadas ao horário de verão.
• Use identificadores, não abreviações. Europe/London lida com o horário de verão automaticamente; GMT/BST não.

Conclusão

date_default_timezone_set() oferece controle explícito sobre como o PHP renderiza datas e horários, mantendo o comportamento consistente entre ambientes. Defina-o deliberadamente, valide identificadores não confiáveis e confirme o fuso ativo com date_default_timezone_get() quando algo parecer errado.

Prática