checkdate()

Introdução

A função checkdate() verifica se um mês, dia e ano formam juntos uma data válida no calendário gregoriano. É a maneira mais simples em PHP de responder a perguntas como "29 de fevereiro é uma data real este ano?" sem precisar analisar strings ou construir um objeto DateTime.

Esta página aborda a sintaxe, os parâmetros e o valor de retorno de checkdate(), como ela lida com anos bissextos e valores fora do intervalo, o limite do intervalo de anos e quando utilizar a classe DateTime em vez disso.

Sintaxe

checkdate(int $month, int $day, int $year): bool

Parâmetros

Valor de retorno

checkdate() retorna true quando a data é válida e false caso contrário. A data é considerada válida quando todas estas condições são verdadeiras: o mês está entre 1 e 12, o ano está entre 1 e 32767, e o dia está dentro do número de dias que o mês especificado possui no ano informado (anos bissextos são considerados).

Exemplo básico

Para verificar se 29 de fevereiro de 2024 é uma data válida (2024 é um ano bissexto, portanto é):

O script armazena o mês, o dia e o ano em variáveis, passa-os para checkdate() e exibe uma mensagem com base no boolean retornado.

Anos bissextos e dias inválidos

O verdadeiro valor de checkdate() está no fato de que ela sabe quantos dias cada mês possui — incluindo a regra do ano bissexto para fevereiro. O mesmo número de dia pode ser válido em um ano e inválido no seguinte:

<?php

var_dump(checkdate(2, 29, 2024)); // bool(true)  — 2024 is a leap year
var_dump(checkdate(2, 29, 2023)); // bool(false) — 2023 is not
var_dump(checkdate(4, 31, 2024)); // bool(false) — April has only 30 days
var_dump(checkdate(13, 1, 2024)); // bool(false) — month out of range
var_dump(checkdate(0, 1, 2024));  // bool(false) — month must be >= 1

Como checkdate() realiza essas verificações internamente, você não precisa codificar manualmente quais meses têm 30 ou 31 dias.

Um uso prático: validar entradas de formulário

Uma aplicação comum de checkdate() é rejeitar datas impossíveis enviadas por um formulário antes de armazená-las ou criar um objeto DateTime:

<?php

function validateDate(int $month, int $day, int $year): string
{
    if (!checkdate($month, $day, $year)) {
        return "Please enter a real calendar date.";
    }

    return "Saved $year-$month-$day.";
}

echo validateDate(2, 30, 2024) . "\n"; // Please enter a real calendar date.
echo validateDate(12, 25, 2024) . "\n"; // Saved 2024-12-25.

O limite do intervalo de anos e a alternativa DateTime

checkdate() aceita apenas anos no intervalo 1–32767, o que é suficiente para a maioria das aplicações, mas inadequado se você precisar de datas fora desse intervalo. Ela também recebe três inteiros separados, portanto você mesmo deve dividir uma string de data antes de usá-la.

Para entrada em string ou validação mais rigorosa, use a classe DateTime do PHP. DateTime::createFromFormat() analisa uma data com base em um formato personalizado, e combiná-la com DateTime::getLastErrors() permite detectar valores que o PHP silenciosamente "rola" (como transformar 30 de fevereiro em 1 ou 2 de março):

<?php

$input = '2024-02-30';
$date = DateTime::createFromFormat('Y-m-d', $input);
$errors = DateTime::getLastErrors();

if ($date === false || $errors['warning_count'] > 0 || $errors['error_count'] > 0) {
    echo "Invalid date: $input";
} else {
    echo "Valid date: " . $date->format('Y-m-d');
}
// Output: Invalid date: 2024-02-30

Se você tiver apenas mês, dia e ano como inteiros, checkdate() é a escolha mais concisa e sem dependências externas.

Funções relacionadas

• mktime() — cria um timestamp Unix a partir de partes individuais de data.
• date() — formata um timestamp em uma string de data legível por humanos.
• strtotime() — converte uma data textual em inglês para um timestamp.
• PHP Date and Time — visão geral sobre como trabalhar com datas em PHP.

Conclusão

checkdate() é a forma mais rápida de confirmar que um mês, dia e ano formam uma data gregoriana real, com os anos bissextos já tratados para você. Lembre-se do limite de anos entre 1 e 32767, e recorra a DateTime::createFromFormat() quando precisar validar strings de data ou trabalhar fora desse intervalo.

Prática