mktime()

A função PHP mktime() constrói um timestamp Unix a partir de partes individuais de data e hora — hora, minuto, segundo, mês, dia e ano. É o inverso de date(): enquanto date() converte um timestamp em uma string formatada, mktime() converte as partes de uma data em um timestamp que você pode armazenar, comparar ou usar em operações aritméticas.

Este capítulo aborda a ordem dos argumentos (que confunde quase todo mundo), como mktime() normaliza automaticamente valores fora do intervalo, seu comportamento em relação ao fuso horário e quando você deve usar as classes DateTime em vez disso.

Sintaxe

mktime(
    int $hour = (current hour),
    ?int $minute = (current minute),
    ?int $second = (current second),
    ?int $month  = (current month),
    ?int $day    = (current day),
    ?int $year   = (current year)
): int|false

O primeiro argumento, $hour, é obrigatório desde o PHP 8.0 — chamar mktime() sem argumentos lança um ArgumentCountError. Qualquer argumento omitido assume como padrão a parte correspondente da data e hora locais atuais. A função retorna o timestamp como um inteiro, ou false se os argumentos produzirem uma data fora do intervalo válido.

Um timestamp Unix é o número de segundos decorridos desde a época Unix — 1º de janeiro de 1970, 00:00:00 UTC. É a moeda comum para datas no PHP, bancos de dados e sistemas operacionais.

Atenção à ordem dos argumentos. mktime() recebe o tempo antes da data: hora, minuto, segundo, mês, dia, ano. Isso é diferente de como normalmente escrevemos datas (ano-mês-dia), sendo a fonte mais comum de bugs.

Construindo um timestamp específico

Para representar um momento fixo, passe todas as seis partes. Aqui construímos 14h30 de 15 de junho de 2024:

Definimos o fuso horário explicitamente para que a saída seja reproduzível. Sem date_default_timezone_set(), mktime() interpreta as partes no fuso horário configurado do servidor, o que pode deslocar o timestamp resultante.

Aritmética de datas com mktime()

Como um timestamp é apenas um número de segundos, você pode somar ou subtrair segundos para avançar ou retroceder uma data. Para encontrar a data 30 dias a partir de um determinado dia, adicione 30 × 86400 segundos (há 86.400 segundos em um dia):

Adicionando 30 dias a uma data

Essa abordagem de segundos brutos funciona bem para dias inteiros, mas ignora as transições de horário de verão: um "dia" nem sempre tem exatamente 86.400 segundos. Para aritmética de calendário correta através das fronteiras de DST, use DateTime::modify() ou DateInterval.

Normalização automática

Um recurso útil de mktime() é que ele normaliza valores fora do intervalo: ele os ajusta para a data correta em vez de falhar. Passe o mês 13 e você obtém janeiro do próximo ano; passe o dia 0 e você obtém o último dia do mês anterior:

Isso torna mktime() conveniente para cálculos do tipo "último dia do mês": mktime(0, 0, 0, $month + 1, 0, $year) retorna o dia final de $month. Observe que essa flexibilidade também significa que mktime() não rejeitará uma data claramente inválida como 30 de fevereiro — ela simplesmente a ajusta silenciosamente. Se você precisar validar uma data do calendário, use checkdate() primeiro.

Armadilhas comuns

• Ordem errada dos argumentos. Escrever mktime(2024, 6, 15) pensando que é ano-mês-dia produz uma data sem sentido. Lembre-se: primeiro o tempo, depois o mês, dia, ano.
• Sem argumentos no PHP 8. mktime() com zero argumentos lança ArgumentCountError. Para obter o timestamp atual, use time().
• Anos com dois dígitos. Passe um ano completo com quatro dígitos. Valores como 0–69 mapeiam para 2000–2069 e 70–100 para 1970–2000, o que raramente é o desejado.

mktime() vs. as classes DateTime

mktime() é procedural e trabalha no fuso horário local. Para partes UTC, use seu equivalente gmmktime(). Para código novo, prefira as classes orientadas a objetos DateTime e DateTimeImmutable — elas carregam informações de fuso horário, lidam com aritmética que respeita o DST e evitam cálculos manuais em segundos:

Conclusão

mktime() constrói um timestamp Unix a partir de partes de data e hora, normalizando automaticamente valores fora do intervalo — o que o torna útil para aritmética rápida de datas e truques de "último dia do mês". Tenha em mente suas peculiaridades: o tempo vem antes da data na lista de argumentos, e uma chamada sem argumentos agora gera erro (use time() para "agora"). Para trabalho com fuso horário correto e que respeite o DST no PHP moderno, use DateTimeImmutable e DateInterval. Veja também checkdate() para validação e strtotime() para analisar strings de data em formato legível por humanos.

Prática