idate()

idate() é uma função PHP integrada que extrai uma única informação de data ou hora de um timestamp Unix e a retorna como um inteiro. O nome significa integer date (data inteira). Ao contrário de date(), que monta uma string formatada a partir de um ou mais caracteres de formato, idate() aceita exatamente um caractere de formato e devolve um número simples com o qual você pode realizar cálculos imediatamente.

Esta página aborda a sintaxe, os caracteres de formato que idate() entende, exemplos executáveis, como ela difere de date() e as armadilhas a serem observadas.

Sintaxe

idate(string $format, ?int $timestamp = null): int|false

• $format — um único caractere de formato (veja a tabela abaixo). Passar uma string com mais de um caractere gera um aviso e retorna false.
• $timestamp — um timestamp Unix opcional (segundos desde 1º de janeiro de 1970, UTC). Se omitido, a data e hora atuais são usadas.

Retorna um inteiro, ou false em caso de falha.

Caracteres de formato

idate() suporta um subconjunto dos caracteres de formato de date() — apenas aqueles que produzem um valor numérico.

Importante: idate() retorna um número, não uma string com zero à esquerda. idate('m') para março retorna o inteiro 3, não "03". Se precisar de zero à esquerda, use date('m') em vez disso, que retorna a string "03".

Exemplo básico

<?php
// March 5, 2023, 17:30:45
$timestamp = mktime(17, 30, 45, 3, 5, 2023);

echo idate('Y', $timestamp) . "\n"; // 2023
echo idate('m', $timestamp) . "\n"; // 3
echo idate('d', $timestamp) . "\n"; // 5
echo idate('H', $timestamp) . "\n"; // 17
echo idate('i', $timestamp) . "\n"; // 30
echo idate('s', $timestamp) . "\n"; // 45

Como o valor de retorno é um inteiro, você pode usá-lo diretamente em operações aritméticas e comparações:

<?php
$timestamp = mktime(17, 30, 45, 3, 5, 2023);

if (idate('N', $timestamp) >= 6) {
    echo "It's the weekend.\n";
} else {
    echo "It's a weekday.\n";
}

// March 5, 2023 was a Sunday (N = 7), so this prints:
// It's the weekend.

Usando a hora atual

Quando você omite o segundo argumento, idate() lê a data e hora atuais, o que a torna conveniente para verificações rápidas:

<?php
$currentYear = idate('Y');

echo "The current year is {$currentYear}.\n";

// Detect a leap year
echo idate('L') ? "This year is a leap year.\n" : "This year is not a leap year.\n";

idate() vs. date()

<?php
$timestamp = mktime(9, 5, 0, 4, 2, 2024);

echo date('m', $timestamp) . "\n";  // "04"  (string, zero-padded)
echo idate('m', $timestamp) . "\n"; // 4     (integer, no padding)

Quando usar

Recorra a idate() quando quiser um componente de data/hora como número — por exemplo, para construir um contador, comparar dois valores, indexar em um array ou alimentar o resultado em cálculos adicionais. Se o objetivo é exibir uma data ou hora formatada, use date() (ou strtotime() para primeiro converter texto em timestamp).

Armadilhas

• Sem formatos com múltiplos caracteres. idate('Y-m-d') não funciona — gera um aviso e retorna false. Chame idate() uma vez por componente, ou use date().
• Sem zeros à esquerda. Não dependa de idate() para saída de largura fixa; ela sempre remove o preenchimento.
• false parece 0. Em caso de falha, idate() retorna false, que é levemente igual a 0. Use uma verificação estrita (=== false) se um 0 real (como um domingo retornado por w) for um resultado válido.

Funções relacionadas

• date() — formata um timestamp como string.
• mktime() — constrói um timestamp Unix a partir de partes de data/hora.
• strtotime() — converte uma string de data em inglês em um timestamp.
• time() — obtém o timestamp Unix atual.

Prática

Prática