Análise de Datas em PHP

As datas frequentemente chegam como strings simples — de um campo de formulário, um arquivo CSV ou uma resposta de API — e o PHP não tem como saber como essas strings estão organizadas a menos que você o informe. A função date_parse_from_format() permite analisar uma string de data com base em um formato explícito e inspecionar o resultado, incluindo quaisquer erros ou avisos. Esta página explica como a função funciona, como interpretar seu valor de retorno, como validar entradas e quando utilizar uma ferramenta diferente, como DateTime ou strtotime().

O que significa análise de datas

A análise de datas é o processo de transformar uma string como "2023-03-03" em dados estruturados — um ano, um mês, um dia, e assim por diante — com os quais seu programa pode trabalhar. A dificuldade está na ambiguidade: 03/04/2023 pode ser o dia 4 de março ou o dia 3 de abril, dependendo da convenção, e 2023-13-45 parece uma data, mas não é válida.

date_parse_from_format() elimina essa ambiguidade exigindo que você forneça o formato exato com antecedência. Ela lê a string estritamente de acordo com esse formato e informa o que encontrou, para que você possa decidir se a entrada era válida.

A função date_parse_from_format()

date_parse_from_format() analisa uma string de data usando um formato específico e retorna um array associativo descrevendo a data analisada: ano, mês, dia, hora, minuto, segundo, além de avisos e erros coletados durante a leitura da string.

Sintaxe

date_parse_from_format(string $format, string $datetime): array

• $format — uma string de formato usando os mesmos marcadores de posição que date(), por exemplo Y-m-d para 2023-03-03 ou d/m/Y para 03/03/2023.
• $datetime — a string de data a ser analisada.

A função sempre retorna um array; ela nunca lança exceções. Para saber se a análise foi bem-sucedida, você deve verificar as chaves error_count e warning_count.

Um exemplo básico

A saída deste código será:

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

A função analisou "2023-03-03 10:30:00" com base no formato Y-m-d H:i:s e preencheu cada componente. Você pode ler valores individuais diretamente do array, como $date_array['year'] ou $date_array['month']. Quando um componente está ausente na string de formato, seu valor é retornado como false (exibido como um valor vazio pelo print_r).

Analisando formatos personalizados

Os marcadores de posição do formato são os mesmos usados por date(), portanto qualquer layout que você possa produzir, também pode analisar. O exemplo abaixo lê uma data no estilo europeu dia/mês/ano:

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

Isso imprime:

Day:   3
Month: 3
Year:  2023

Como apenas d, m e Y aparecem no formato, as chaves hour, minute e second são retornadas como false.

Validando o resultado: erros e avisos

date_parse_from_format() nunca lança uma exceção — mesmo com entradas inválidas, ela retorna um array. Duas chaves indicam se a entrada era utilizável:

• error_count conta os caracteres que não corresponderam ao formato de forma alguma.
• warning_count conta os valores que corresponderam ao formato, mas não fazem sentido, como o mês 13 ou o dia 45.

Uma string que não corresponde ao formato produz erros:

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

Uma string que corresponde ao formato, mas não é uma data real, produz um aviso:

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Sempre verifique ambas as contagens antes de confiar nos valores analisados:

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

Quando usar uma função diferente

date_parse_from_format() é mais adequada quando você deseja um relatório detalhado com reconhecimento de formato — especialmente para validar entradas. Se você apenas precisa de um valor de data utilizável, outras ferramentas são mais convenientes:

• DateTime::createFromFormat($format, $string) retorna um objeto DateTime pronto para uso, que você pode formatar ou realizar operações aritméticas. Veja data e hora em PHP.
• strtotime() adivinha o formato por você e retorna um timestamp Unix — prático para strings comuns e não ambíguas, mas mais arriscado para layouts específicos de localidade.
• date_parse() é igual a esta função, mas sem uma string de formato; ela tenta interpretar a data por conta própria.

Conclusão

date_parse_from_format() analisa uma string de data com base em um formato explícito e retorna um array associativo detalhado, tornando-a ideal para validar datas fornecidas pelo usuário. Lembre-se de que ela nunca lança exceções — verifique error_count e warning_count antes de usar o resultado. Quando você precisar de um objeto DateTime ou de um timestamp, utilize DateTime::createFromFormat() ou strtotime().

Prática