PHP Date

Introdução

Quase toda aplicação precisa ler, formatar ou fazer cálculos com datas: entradas de log, rótulos como "publicado há 3 dias", agendamentos, verificações de expiração. O PHP oferece dois conjuntos de ferramentas paralelos para isso:

• Funções procedurais baseadas no timestamp Unix — um inteiro que conta os segundos desde 1º de janeiro de 1970, 00:00:00 UTC. time(), date(), strtotime() e mktime() pertencem a este grupo.
• A API orientada a objetos DateTime — DateTime, DateTimeImmutable, DateTimeZone e DateInterval — que é mais segura para aritmética e manipulação de fuso horário.

Esta página aborda as funções e classes mais utilizadas, quando escolher cada uma e a armadilha de fuso horário que confunde quase todos.

Uma observação sobre fusos horários

Por padrão, o PHP usa o fuso horário configurado no php.ini (a configuração date.timezone). Se isso não estiver definido, você pode obter resultados inconsistentes entre servidores. Defina-o explicitamente no início do seu script, ou passe um DateTimeZone para cada objeto:

date_default_timezone_set('UTC');

Consulte PHP Timezones para obter a lista completa de identificadores válidos e como converter entre fusos.

A Função date()

date(string $format, ?int $timestamp = null) formata um timestamp em uma string legível por humanos. Quando o timestamp é omitido, utiliza a hora atual. Esta é a principal função para exibição de datas.

echo date('Y-m-d H:i:s'); // e.g. 2023-10-25 14:30:00
echo date('l, F j, Y');   // e.g. Wednesday, October 25, 2023

A string format é construída com marcadores de um único caractere. Os mais comuns:

Para imprimir uma letra literal que também seja um caractere de formato, escape-a com uma barra invertida: date('\T\o\d\a\y: Y-m-d').

A Função time()

time() retorna o timestamp Unix atual como um inteiro. Use-a sempre que precisar de um "agora" numérico para armazenar, comparar ou realizar aritmética.

$now = time();
echo $now; // an integer such as 1698241800

// One hour from now:
echo date('Y-m-d H:i:s', $now + 3600);

Como um timestamp é simplesmente um inteiro de segundos, você pode adicionar ou subtrair durações diretamente (+ 3600 para uma hora, + 86400 para um dia). Para algo mais complexo do que alguns offsets fixos, prefira a aritmética com DateTime abaixo.

A Função strtotime()

strtotime(string $datetime, ?int $baseTimestamp = null) converte uma data/hora textual em inglês para um timestamp, retornando false em caso de falha. Ela entende tanto strings absolutas quanto frases relativas.

echo strtotime('2023-10-25 14:30:00'); // 1698244200 (UTC)
echo "\n";
var_dump(strtotime('next monday'));    // a future timestamp, or false if unparseable

$tomorrow = strtotime('+1 day');
echo date('Y-m-d', $tomorrow);

Sempre verifique se o resultado é false antes de usá-lo, pois um erro de digitação falha silenciosamente em vez de lançar uma exceção.

A Função mktime()

mktime(int $hour, int $minute, int $second, int $month, int $day, int $year) constrói um timestamp a partir de componentes individuais. Observe que a ordem dos argumentos é hora primeiro, depois data.

$timestamp = mktime(0, 0, 0, 12, 31, 2023);
echo date('Y-m-d', $timestamp); // 2023-12-31

mktime() normaliza valores fora do intervalo, o que é útil: mktime(0, 0, 0, 13, 1, 2023) transforma o "mês 13" em janeiro de 2024.

A Classe DateTime

new DateTime(string $datetime = 'now', ?DateTimeZone $timezone = null) encapsula uma data em um objeto que você pode formatar, comparar e modificar com chamadas de método. (A função date_create() é um alias procedural para o mesmo construtor.)

$date = new DateTime('2023-10-25', new DateTimeZone('UTC'));
echo $date->format('Y-m-d'); // 2023-10-25

DateTime é mutável — métodos como modify() alteram o objeto no lugar. Essa é a fonte de bugs sutis quando um objeto é compartilhado, razão pela qual a versão imutável abaixo geralmente é preferida.

A Classe DateTimeImmutable

DateTimeImmutable tem a mesma API que DateTime, mas todo método modificador retorna um novo objeto e deixa o original intocado. Para código moderno, esta é a opção mais segura por padrão.

$date = new DateTimeImmutable('2023-10-25');
$newDate = $date->modify('+1 day');
echo $date->format('Y-m-d');    // 2023-10-25 (unchanged)
echo "\n";
echo $newDate->format('Y-m-d'); // 2023-10-26

O Método DateTime::format()

format(string $format) converte um objeto DateTime ou DateTimeImmutable em uma string. Ele aceita os mesmos caracteres de formato que a função date().

$date = new DateTimeImmutable('2023-10-25 14:30:00');
echo $date->format('l, F j, Y'); // Wednesday, October 25, 2023

Aritmética e diferenças de datas

A API orientada a objetos se destaca na aritmética. Use DateInterval (strings de duração ISO-8601) para adicionar ou subtrair, e diff() para comparar duas datas:

$start = new DateTimeImmutable('2023-10-25');
$later = $start->add(new DateInterval('P10D')); // P10D = 10 days
echo $later->format('Y-m-d'); // 2023-11-04

$diff = $start->diff(new DateTimeImmutable('2023-12-31'));
echo "\n" . $diff->days . ' days apart'; // 67 days apart

Escolhendo a ferramenta certa

• Precisa de um "agora" formatado rapidamente? Use date().
• Armazenando ou comparando um momento numericamente? Use time() / timestamps Unix.
• Fazendo parse de entrada do usuário ou de logs? Use strtotime() (e verifique se retornou false).
• Fazendo aritmética, diferenças ou conversões de fuso horário? Use DateTimeImmutable com DateInterval.

Armadilhas comuns

• Fuso horário não definido. Sem date_default_timezone_set() ou um valor no php.ini, os resultados variam por servidor. Defina-o uma vez, no início.
• strtotime() retorna false para strings não reconhecidas — nunca lança exceção, então sempre valide.
• DateTime é mutável. modify() altera o original; prefira DateTimeImmutable para evitar surpresas com estado compartilhado.
• Timestamps são segundos UTC. Formatá-los com date() aplica o fuso horário atual, então o mesmo inteiro pode ser exibido de forma diferente dependendo das suas configurações.

Conclusão

O PHP oferece um toolkit de timestamps procedural (date(), time(), strtotime(), mktime()) e um orientado a objetos (DateTime, DateTimeImmutable). Use timestamps simples para exibição e armazenamento básicos, e DateTimeImmutable para aritmética e lógica com reconhecimento de fuso horário. Para aprofundamento, consulte PHP Date and Time, a referência de date(), strtotime() e mktime().

Prática