Data e Hora no PHP

Quase toda aplicação web precisa lidar com datas e horas: timestamps em postagens, datas de expiração, rótulos "há 3 dias", agendamento, registro de logs. O PHP oferece duas ferramentas complementares para isso — a família de funções procedurais date() para formatação rápida, e a classe orientada a objetos DateTime para aritmética de datas mais segura e poderosa.

Este capítulo mostra como exibir a data atual, controlar o fuso horário, converter strings legíveis por humanos em timestamps e calcular a diferença entre duas datas — além dos erros mais comuns que costumam pegar as pessoas de surpresa.

Como o PHP representa o tempo

Internamente, o PHP armazena um ponto no tempo como um timestamp Unix: o número de segundos decorridos desde a meia-noite UTC de 1º de janeiro de 1970. time() retorna o timestamp atual, e a maioria das funções de data aceita um como entrada:

<?php

echo time();          // e.g. 1750464000 (an integer)
echo date("Y-m-d");   // turns "now" into a readable string

?>

Um timestamp é independente do fuso horário — representa o mesmo instante em qualquer lugar do mundo. O fuso horário só importa quando você formata esse instante em uma string legível por humanos, por isso definir o fuso horário corretamente é importante (veja abaixo).

Uso básico de date()

A função date() converte um timestamp em uma string formatada:

date(string $format, ?int $timestamp = null): string

• $format é uma string de caracteres de formato que descreve como a saída deve ficar.
• $timestamp é opcional. Se omitido, date() usa o horário atual.

Aqui está a data atual no formato dd/mm/yyyy:

Qualquer caractere que não seja um código de formato é impresso literalmente, então você pode incluir separadores e texto:

<?php

echo date("l, F j, Y");      // e.g. Saturday, June 21, 2025
echo "\n";
echo date("Y-m-d H:i:s");    // e.g. 2025-06-21 14:30:05

?>

Códigos de formato

date() aceita dezenas de caracteres de formato. Estes são os mais utilizados:

Para imprimir uma letra que seja um código de formato (por exemplo, um H literal), escape-a com uma barra invertida: date('\H:i').

Definindo o fuso horário

date() formata os horários de acordo com o fuso horário padrão do servidor. Depender do padrão do servidor é uma fonte comum de bugs do tipo "o horário está errado em algumas horas". Defina o fuso horário explicitamente no início do seu script (ou no php.ini):

<?php

date_default_timezone_set("America/New_York");

echo date("Y-m-d H:i:s");   // formatted for New York time

?>

Use os nomes de fuso horário da IANA como Europe/London, Asia/Tokyo ou UTC. Para uma visão geral de como o PHP lida com regiões e horário de verão, consulte o capítulo PHP Timezones.

Analisando strings em timestamps

Quando uma data chega como texto — de um formulário, uma API ou um banco de dados — strtotime() a converte em um timestamp que você pode formatar ou usar em cálculos. Ela entende tanto datas absolutas quanto frases relativas em inglês:

strtotime() é tolerante, mas ambígua. Uma string como 01/02/2022 é lida como mês/dia (estilo americano). Para análise previsível de um formato conhecido, prefira DateTime::createFromFormat() (abaixo). Quando strtotime() não consegue interpretar a entrada, ela retorna false, então sempre verifique o resultado. Consulte o capítulo dedicado ao strtotime() para a lista completa de frases aceitas.

A classe DateTime

Para qualquer coisa além de exibição simples, a API orientada a objetos DateTime é a abordagem moderna e recomendada. Ela evita os limites de overflow de inteiros, lida com fusos horários de forma limpa e torna a aritmética de datas legível:

<?php

$date = new DateTime("2022-01-01 12:00:00");

// Format it
echo $date->format("l, F j, Y");   // Saturday, January 1, 2022
echo "\n";

// Add or subtract durations with DateInterval
$date->modify("+10 days");
echo $date->format("Y-m-d");        // 2022-01-11

?>

DateTimeImmutable funciona da mesma forma, mas nunca altera o objeto original — modify() retorna uma nova instância. Prefira-a quando você passa datas entre funções, para que um método chamado em outro lugar não possa mutar silenciosamente seu valor.

Calculando a diferença entre duas datas

DateTime::diff() retorna um DateInterval descrevendo a diferença entre duas datas, o que é muito mais seguro do que subtrair timestamps brutos:

<?php

$start = new DateTime("2022-01-01");
$end   = new DateTime("2022-03-15");

$diff = $start->diff($end);

echo $diff->days . " days total\n";      // 73 days total
echo $diff->format("%m months, %d days"); // 2 months, 14 days

?>

Para o equivalente em estilo funcional, consulte o capítulo date_diff().

Erros comuns

• O problema de 2038. Em sistemas de 32 bits, date() e strtotime() trabalham com inteiros de 32 bits com sinal e falham em 2038-01-19 03:14:07 UTC. DateTime não é afetado, então use-o para datas muito distantes no futuro ou no passado.
• date() não é Date(). Nomes de funções PHP não diferenciam maiúsculas de minúsculas, mas os códigos de formato são sensíveis a maiúsculas: m (mês) e M (nome do mês) são diferentes.
• Aviso de fuso horário ausente. Sem um fuso horário configurado, versões mais antigas do PHP emitem um aviso. Chame date_default_timezone_set() no início.
• strtotime() retorna false, não 0, em caso de falha — e 0 é um timestamp válido (a época Unix), então teste com === false.

Conclusão

O PHP oferece um espectro de ferramentas para datas e horas. Use date() e time() para formatação rápida, strtotime() para analisar strings recebidas, e as classes DateTime / DateTimeImmutable para aritmética com fuso horário e comparações de datas. Defina seu fuso horário explicitamente, valide entradas analisadas e prefira DateTime sempre que precisar adicionar, subtrair ou comparar datas.

Em seguida, explore os componentes básicos em profundidade: a função date() do PHP, strtotime() e PHP Timezones.

Prática