gmmktime()

O que é a Função gmmktime() do PHP?

A função gmmktime() do PHP constrói um timestamp Unix a partir das partes individuais de uma data e hora (hora, minuto, segundo, mês, dia, ano), interpretando essas partes como GMT/UTC em vez do fuso horário local do servidor. Um timestamp Unix é simplesmente o número de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC — o valor que a maioria das funções de data do PHP usa internamente.

Esta página aborda a sintaxe e os parâmetros da função, como ela difere de mktime(), como valores fora do intervalo são normalizados automaticamente, e o problema que afeta a maioria das pessoas: no PHP moderno os parâmetros não são todos opcionais.

O nome é lido como greenwich mean time + make time.

Sintaxe

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

Retorna o timestamp como um inteiro, ou false se os argumentos descreverem um horário inválido.

Parâmetros

Atenção: No PHP 8.0 e posteriores, chamar gmmktime() sem argumentos lança um ArgumentCountError — hour é obrigatório. Qualquer argumento que você omitir usa como padrão o valor correspondente do horário GMT atual. Para obter o timestamp de "agora", use time().

Exemplo Básico

Isso gera o timestamp Unix para 3 de março de 2023 às 12:30:00 PM GMT. Para lê-lo de volta em formato legível, combine-o com gmdate():

<?php

$timestamp = gmmktime(12, 30, 0, 3, 3, 2023);
echo gmdate('Y-m-d H:i:s', $timestamp);
// 2023-03-03 12:30:00

gmmktime() vs. mktime()

gmmktime() e mktime() recebem exatamente os mesmos argumentos e retornam um timestamp Unix — a única diferença é o fuso horário em que as partes são interpretadas. gmmktime() as trata como GMT/UTC; mktime() as trata como o fuso horário local do servidor. Com os mesmos dados de entrada, elas produzem timestamps diferentes sempre que o horário local está deslocado em relação ao UTC:

<?php

date_default_timezone_set('America/New_York'); // UTC-4 in June

echo gmmktime(12, 0, 0, 6, 15, 2023), "\n"; // 1686830400  (12:00 UTC)
echo mktime(12, 0, 0, 6, 15, 2023), "\n";    // 1686844800  (12:00 New York = 16:00 UTC)

Use gmmktime() quando suas entradas já estiverem em UTC (timestamps de uma API, um banco de dados armazenado em UTC, etc.) para que o resultado não mude conforme a configuração de fuso horário do servidor.

Valores Fora do Intervalo São Normalizados

Você não precisa manter as partes dentro dos intervalos normais. gmmktime() as normaliza, o que é útil para aritmética de datas sem carregamento manual:

<?php

// Month 13 rolls into the next year
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 13, 1, 2023)), "\n"; // 2024-01-01

// Day 32 of January becomes February 1st
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 1, 32, 2023)), "\n"; // 2023-02-01

// Hour 25 rolls into the next day at 01:00
echo gmdate('Y-m-d H:i', gmmktime(25, 0, 0, 1, 1, 2023)), "\n"; // 2023-01-02 01:00

Isso faz com que expressões como gmmktime(0, 0, 0, $month, $day + 7, $year) ("sete dias depois") funcionem corretamente através dos limites de mês e ano.

Quando Usar gmmktime()

• Consistência de fuso horário. Como sempre usa UTC, os mesmos argumentos produzem o mesmo timestamp em qualquer servidor, independentemente de date.timezone.
• Construindo timestamps a partir de partes. Quando você tem valores separados de hora/dia/mês (por exemplo, de um formulário ou string analisada) em vez de uma única string de data. Para uma string de data completa como "2023-03-03 12:30", prefira strtotime().
• Aritmética de datas via normalização. Adicione ou subtraia de um componente e deixe a função normalizar o resultado.

Se você só precisa validar que uma combinação de mês/dia/ano é uma data de calendário real, consulte checkdate().

Conclusão

gmmktime() transforma componentes separados de data e hora em um timestamp Unix baseado em UTC. Seus pontos fortes são a independência de fuso horário e a normalização automática de valores fora do intervalo. Lembre-se que, ao contrário de versões mais antigas do PHP, o PHP 8+ requer pelo menos o argumento hour, e use mktime() quando suas entradas estiverem no horário local e gmdate() para formatar o resultado.

Prática