A Função date_get_last_errors() do PHP

Você está cansado de lidar com erros relacionados a datas no seu código PHP? Se sim, você está com sorte. A função date_get_last_errors() do PHP está aqui para ajudar.

Neste artigo, vamos fazer um mergulho profundo em como a função date_get_last_errors() funciona, seus vários parâmetros e como você pode usá-la para solucionar problemas relacionados a datas no seu código PHP.

O que é a Função date_get_last_errors()?

A função date_get_last_errors() é uma função PHP nativa (disponível desde o PHP 5.2.0) que permite recuperar informações sobre o último erro ou aviso relacionado a datas que ocorreu. Ela retorna um array associativo contendo warning_count, warnings, error_count e errors, que fornecem os códigos específicos e as descrições textuais do que deu errado durante a última operação de data/hora.

Como Usar date_get_last_errors()

Para usar a função date_get_last_errors(), você a chama após uma função de criação ou modificação de data falhar. Para código pronto para produção, você deve sempre verificar se a função de data retornou false antes de recuperar os detalhes do erro. Aqui está um exemplo:

Neste exemplo, estamos tentando criar um objeto de data a partir da string '2022-13-01', que é um valor de data inválido (o mês 13 não existe). Após verificar que date_create_from_format() retornou false, chamamos date_get_last_errors() e imprimimos o array retornado usando print_r().

A saída deste código será:

Array
(
    [warning_count] => 1
    [warnings] => Array
        (
            [10] => The parsed date was invalid
        )

    [error_count] => 0
    [errors] => Array
        (
        )

)

Como você pode ver, o array retornado distingue entre avisos e erros:

• Erros significam que a entrada não pôde ser analisada de forma alguma (por exemplo, um caractere inválido ou um formato que não corresponde à string).
• Avisos significam que a string foi analisada, mas o resultado é questionável — como um componente fora do intervalo. O mês 13 não existe, então o PHP o ajusta ou rejeita e emite o aviso [10] => The parsed date was invalid.

Atenção: o Valor de Retorno Quando Não Há Erros

Uma armadilha comum é que o valor de retorno mudou entre as versões do PHP:

• PHP 5.2 – 8.1: sempre retorna o array associativo, com warning_count e error_count definidos como 0 quando nada deu errado.
• PHP 8.2 e posterior: retorna false (boolean) quando a operação de data anterior não produziu avisos nem erros.

É exatamente por isso que você deve fazer a verificação no resultado da própria função de data, em vez de em date_get_last_errors():

<?php
// A valid date — parsing succeeds.
$result = date_create_from_format('Y-m-d', '2022-01-15');

if ($result === false) {
    // This branch is skipped because the date is valid.
    print_r(date_get_last_errors());
} else {
    echo "Parsed successfully: " . $result->format('Y-m-d');
}
?>

Saída:

Parsed successfully: 2022-01-15

Como $result é um objeto DateTime válido, nunca chamamos date_get_last_errors() — evitando completamente a surpresa de false versus array que depende da versão.

Fluxo de Depuração Prático

Ao lidar com análise de datas em produção, siga este padrão para capturar e registrar problemas com segurança:

1. Chame a função de criação de data (por exemplo, date_create_from_format() ou DateTime::createFromFormat()).
2. Verifique se o resultado é false.
3. Se for false, chame date_get_last_errors() para inspecionar os arrays warnings e errors.
4. Registre ou exiba os códigos e mensagens específicos de aviso/erro para identificar o problema exato de análise sem interromper a sua aplicação.

Parâmetros

A função date_get_last_errors() não recebe parâmetros. Ela simplesmente retorna informações sobre o último erro ou aviso relacionado a datas que ocorreu (um array associativo ou false no PHP 8.2+ quando não houve nenhum).

Equivalente Orientado a Objetos

Se você trabalha com a classe DateTime em vez das funções procedurais, as mesmas informações estão disponíveis através do método estático DateTime::getLastErrors():

<?php
$result = DateTime::createFromFormat('Y-m-d', 'not-a-date');

if ($result === false) {
    print_r(DateTime::getLastErrors());
}
?>

Saída:

Array
(
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 3
    [errors] => Array
        (
            [0] => A four digit year could not be found
            [10] => Not enough data available to satisfy format
        )

)

Desta vez a string não pode ser analisada de forma alguma, portanto os problemas são reportados como erros (não avisos). DateTime::getLastErrors() retorna a estrutura idêntica à de date_get_last_errors() e segue as mesmas regras de versão descritas acima.

Funções Relacionadas

• date_create_from_format() — analisa uma string de data com base em um formato explícito; a função cujos erros você inspeciona aqui.
• date_create() — cria um objeto DateTime a partir de uma string de data flexível.
• checkdate() — valida uma data gregoriana antes de tentar analisá-la.
• date() — formata um timestamp assim que você tiver uma data válida.

Conclusão

A função date_get_last_errors() é uma ferramenta valiosa para qualquer desenvolvedor PHP que precise solucionar erros relacionados a datas. Ao expor o aviso ou erro específico que ocorreu durante a última operação de data/hora, ela permite depurar problemas de análise sem interromper a sua aplicação. Lembre-se dos dois hábitos principais: sempre faça a verificação no valor de retorno da própria função de data (false) e leve em conta a mudança do PHP 8.2+ onde date_get_last_errors() em si retorna false quando nada deu errado.

Prática