date()

Introdução

Quase toda aplicação precisa eventualmente exibir, armazenar ou comparar uma data: uma linha "publicado em", uma contagem regressiva, uma verificação de validade. Este capítulo explica como as ferramentas de data e hora do PHP funcionam e quando usar cada uma delas. Começamos pelas funções do dia a dia — date(), time() e strtotime() — passamos para a manipulação e comparação de datas, e terminamos com os pontos onde as pessoas mais erram: fusos horários e horário de verão.

Trabalhando com Datas em PHP

O PHP oferece dois conjuntos de ferramentas complementares para datas:

• Funções procedurais — date(), time(), mktime() e strtotime() — que trabalham com um timestamp Unix (um inteiro simples: o número de segundos desde 1º de janeiro de 1970 UTC). São rápidas para formatação e aritmética simples.
• A API orientada a objetos DateTime — as classes DateTime, DateInterval e DateTimeZone — que é mais legível para qualquer coisa que envolva intervalos, comparações ou fusos horários, e é a abordagem recomendada para código novo.

Este capítulo usa ambas para que você reconheça cada estilo em bases de código reais.

A Função date()

A função date() converte um timestamp em uma string formatada. Recebe uma string de formato como primeiro parâmetro e um timestamp opcional como segundo; quando o timestamp é omitido, date() usa o horário atual.

Isso exibe a data atual no formato "Mês Dia, Ano", como March 3, 2023.

Cada letra na string de formato é um marcador de posição. A tabela abaixo lista os caracteres mais usados:

Qualquer caractere que não seja um marcador reconhecido é impresso literalmente, então date("Y-m-d H:i:s") produz um valor como 2023-03-03 14:09:05. Para imprimir uma letra literal que de outra forma seria um marcador, escape-a com uma barra invertida: date('l \t\h\e jS'). Para a lista completa de marcadores, consulte o capítulo date-format().

A Função time()

A função time() retorna o timestamp Unix atual — o número de segundos decorridos desde 1º de janeiro de 1970 UTC. Não recebe argumentos e é o ponto de partida usual para aritmética de datas, pois inteiros são fáceis de somar e comparar.

Isso exibe o timestamp Unix atual, um inteiro longo como 1646369616. Combine com date() para formatar "agora": date("Y-m-d", time()). Consulte o capítulo time() para mais detalhes.

A Função strtotime()

A função strtotime() analisa uma data textual em inglês — "March 3, 2023", "next Monday", "+2 weeks" — e retorna o timestamp Unix correspondente. É notavelmente flexível, o que a torna prática para converter entradas humanas em um timestamp que pode ser formatado ou comparado.

Isso exibe o timestamp Unix para 3 de março de 2023: 1677801600.

Atenção: se strtotime() não conseguir analisar a string, retorna false, não um erro. Sempre verifique o resultado antes de usá-lo — if (($ts = strtotime($input)) === false) { /* data inválida */ } — caso contrário, false é silenciosamente convertido para 0, que é formatado como 1º de janeiro de 1970. Consulte o capítulo strtotime() para a gramática completa que ela aceita.

Manipulando Datas em PHP

Além de formatar datas, o PHP também fornece uma variedade de funções para manipulá-las. Essas funções permitem adicionar ou subtrair tempo de uma data, comparar datas e muito mais.

Adicionando e Subtraindo Tempo com strtotime()

strtotime() faz mais do que analisar datas fixas — também entende expressões relativas. Passe um timestamp base como segundo argumento e uma expressão como "+1 day", "-3 weeks" ou "first day of next month" como primeiro, e você obterá um novo timestamp.

Isso exibirá a data um dia após 3 de março de 2023, que é "March 4, 2023".

Os Métodos DateTime::add() e DateTime::sub()

Os métodos orientados a objetos DateTime::add() e DateTime::sub() adicionam ou subtraem um DateInterval de um objeto DateTime. Um DateInterval é construído a partir de uma string de duração ISO 8601: P1D significa "um período de 1 dia", P2W é duas semanas e PT1H30M é uma hora e trinta minutos (o T separa a parte de data da parte de hora).

Esse estilo é preferido para código novo porque a operação se lê como uma frase e o objeto controla seu próprio fuso horário.

Isso exibe a data um dia após 3 de março de 2023: March 4, 2023. Os capítulos dedicados date-add() e date-sub() aprofundam o tema, e date-diff() mostra como obter o intervalo entre dois objetos DateTime.

Comparando Datas em PHP

Como timestamps são inteiros simples, você pode comparar duas datas com os operadores comuns <, > e == uma vez que ambos os lados sejam timestamps. Converta cada string de data com strtotime() primeiro.

Isso exibe Date 1 is earlier than Date 2. Para comparar objetos DateTime, você pode usar os mesmos operadores diretamente ($a < $b) sem converter para timestamps.

Fusos Horários e Horário de Verão

A parte mais complicada de trabalhar com datas é garantir que elas se refiram ao mesmo momento em diferentes regiões. date() e time() interpretam timestamps no fuso horário padrão configurado do PHP, então acertar essa configuração é importante.

A Função date_default_timezone_set()

date_default_timezone_set() define o fuso horário padrão usado por todas as funções de data e hora para o restante da requisição. Chame-a uma vez, no início do seu script, passando um identificador IANA válido como America/New_York ou Europe/London.

<?php
    date_default_timezone_set("America/New_York");
    echo date("Y-m-d H:i:s");
?>

Uma lista de identificadores válidos está no capítulo php-timezones; a leitura da configuração atual é abordada em date-default-timezone-get().

A Classe DateTimeZone

Quando você precisa de fusos horários diferentes no mesmo script — por exemplo, exibindo o horário de um evento para usuários em várias regiões — definir o padrão uma vez não é suficiente. A classe DateTimeZone permite que um objeto DateTime específico carregue seu próprio fuso:

<?php
    $timezone = new DateTimeZone("America/New_York");
    $date = new DateTime("2023-03-03 09:00", $timezone);
    echo $date->format("Y-m-d H:i T");
?>

Isso formata a data no horário de Nova York e imprime a abreviação do fuso (T), por exemplo 2023-03-03 09:00 EST.

Trabalhando com Horário de Verão

O horário de verão (DST) adianta ou atrasa o relógio, de modo que o deslocamento de um fuso como America/New_York não é fixo (EST vs EDT). O PHP lida com a mudança para você desde que você use um fuso nomeado em vez de um deslocamento fixo. O caractere de formato I (i maiúsculo) de date() indica se o horário de verão está em vigor: 1 se estiver, 0 se não estiver.

Isso exibe se o horário de verão está ou não em vigor para o fuso horário padrão atual.

Conclusão

Agora você tem o conjunto principal de ferramentas para datas em PHP: date() para formatar, time() e strtotime() para obter e analisar timestamps, a família DateTime para adicionar, subtrair e comparar, e DateTimeZone para manter diferentes regiões organizadas. Como regra geral, use as funções procedurais para formatações rápidas e pontuais, e a API orientada a objetos DateTime para qualquer coisa que envolva intervalos, comparações ou múltiplos fusos horários. Para um panorama mais amplo, consulte PHP Date and Time.

Prática