time()

Introdução

PHP fornece um conjunto robusto de funções de data e hora essenciais para lidar com dados temporais: registrar eventos, agendar tarefas, calcular durações e exibir datas localizadas. Este guia aborda as ferramentas mais utilizadas — time(), date(), strtotime() e a API de objetos moderna DateTimeImmutable / DateInterval / DateTimeZone — com suas sintaxes e exemplos práticos executáveis.

Alguns conceitos importantes para conhecer primeiro:

• Um timestamp Unix é um inteiro que conta os segundos desde 1º de janeiro de 1970 00:00:00 UTC (a "época"). Ele é independente de fuso horário, o que o torna ideal para armazenar e comparar momentos no tempo.
• Uma string de formato transforma um timestamp em uma string legível por humanos. Cada caractere (Y, m, d, H, …) mapeia para um componente de data.
• PHP renderiza datas usando o fuso horário padrão do servidor. Defina-o explicitamente para evitar surpresas:

<?php

date_default_timezone_set('UTC');

Definir o fuso horário antecipadamente torna date() e time() determinísticos entre servidores. Para uma introdução mais aprofundada, consulte PHP Date and Time.

Função date() do PHP

A função date() formata um timestamp em uma string legível. Ela aceita dois parâmetros: format (obrigatório) e timestamp (opcional, padrão é o horário atual). A string de formato usa caracteres específicos para representar componentes de data.

Exemplo da função date() em PHP

Neste exemplo, Y, m e d representam o ano de quatro dígitos, o mês de dois dígitos e o dia de dois dígitos, respectivamente. A string de formato suporta muitos outros caracteres para horas, minutos, segundos e mais.

Caracteres de formato comuns

Passe um segundo argumento para formatar qualquer timestamp, não apenas o "agora":

<?php

date_default_timezone_set('UTC');

echo date("l, F j, Y", 1678838400); // outputs "Wednesday, March 15, 2023"

Para escapar uma letra literal de modo que não seja tratada como caractere de formato, prefixe-a com uma barra invertida (ex.: date('jS \o\f F')). Para mais opções de formatação, consulte date() e date_format().

Função time() do PHP

A função time() retorna o timestamp Unix atual, que conta o número de segundos desde 1º de janeiro de 1970, 00:00:00 UTC.

Como usar a função time() do PHP?

O inteiro retornado pode ser passado diretamente para date() ou outras funções temporais para processamento adicional. Como o timestamp é apenas um número, você pode fazer aritmética com ele — por exemplo, adicionar 86400 (o número de segundos em um dia) para obter "este horário amanhã":

<?php

date_default_timezone_set('UTC');

$tomorrow = time() + 86400; // 24 * 60 * 60 seconds
echo date("Y-m-d H:i:s", $tomorrow);

Para cálculos de data que respeitem meses, anos bissextos e horário de verão, prefira a API de objetos mostrada abaixo em vez de aritmética bruta com segundos.

Função strtotime() do PHP

A função strtotime() analisa uma descrição textual de data e hora em inglês e a converte em um timestamp Unix. Ela aceita um único argumento string.

Exemplo da função strtotime() do PHP

Isso converte a string de data e hora especificada em seu valor de timestamp Unix correspondente. strtotime() também entende expressões relativas, o que é útil para agendamento:

<?php

date_default_timezone_set('UTC');

echo date("Y-m-d", strtotime("next monday")), "\n";
echo date("Y-m-d", strtotime("2023-03-03 +1 week")); // outputs "2023-03-10"

Se a string não puder ser analisada, strtotime() retorna false, então sempre verifique o resultado antes de passá-lo adiante.

Classe DateInterval do PHP

A classe DateInterval representa uma duração entre duas datas ou horários. O desenvolvimento moderno em PHP normalmente usa DateTimeImmutable para calcular intervalos, pois evita a mutação do objeto de data original.

Exemplo da classe DateInterval do PHP

Isso calcula a diferença entre duas datas. O especificador de formato %R%a exibe o sinal (+ ou -) seguido pelo número total de dias.

Você também pode construir um DateInterval diretamente a partir de uma string de duração ISO 8601 e adicioná-lo ou subtraí-lo de uma data. P1W significa "um período de uma semana":

<?php

$start = new DateTimeImmutable('2023-03-03');
$later = $start->add(new DateInterval('P1W'));
echo $later->format('Y-m-d'); // outputs "2023-03-10"

Como DateTimeImmutable nunca muta o original, $start ainda aponta para 3 de março após a chamada add(). Consulte date_add(), date_sub() e date_diff() para os equivalentes procedurais.

Funções de Fuso Horário do PHP

PHP lida com fusos horários por meio da classe DateTimeZone e métodos relacionados. Eles permitem a conversão entre zonas e a exibição de deslocamentos UTC.

Exemplo de funções de fuso horário do PHP

Isso exibe a data e hora no fuso especificado, junto com sua abreviação (ex.: EST).

Para converter um momento existente de um fuso para outro, use setTimezone(). O instante no tempo permanece o mesmo — apenas sua representação muda:

<?php

$ny = new DateTimeImmutable('2023-03-03 12:00:00', new DateTimeZone('America/New_York'));
$utc = $ny->setTimezone(new DateTimeZone('UTC'));
echo $utc->format('Y-m-d H:i:s T'); // outputs "2023-03-03 17:00:00 UTC"

Nova York está cinco horas atrás do UTC em março, portanto meio-dia em Nova York equivale a 17:00 UTC. Para alterar o fuso horário usado pelas funções procedurais date() e time(), chame date_default_timezone_set().

API procedural vs. API de objetos: qual usar

PHP oferece dois estilos para trabalhar com datas:

• Funções procedurais (time(), date(), strtotime(), getdate(), gmdate()) são concisas e ótimas para formatação rápida ou conversões pontuais.
• A API de objetos (DateTimeImmutable, DateInterval, DateTimeZone) é a escolha recomendada para qualquer coisa que envolva fusos horários, durações ou cálculos de data, pois é explícita, imutável e evita as armadilhas da aritmética de segundos inteiros através de limites de horário de verão.

Uma boa regra prática: use DateTimeImmutable sempre que uma data cruzar um fuso horário ou precisar ser adicionada ou subtraída.

Conclusão

Dominar as funções de data e hora do PHP permite que os desenvolvedores lidem com dados temporais com precisão em diferentes ambientes e fusos horários. Comece com time() e date() para casos simples, use strtotime() para analisar entrada humana e utilize a família DateTimeImmutable para cálculos de data confiáveis.

Prática