date_parse()

Introdução

A função date_parse() em PHP recebe uma string de data legível por humanos e a decompõe em seus componentes individuais — ano, mês, dia, hora, minuto, segundo — retornando-os como um array associativo. Crucialmente, ela também reporta quaisquer avisos e erros encontrados durante a interpretação da string, o que a torna uma ferramenta útil para validar entradas de data antes de processá-las.

Ao contrário de strtotime(), que converte uma string de data em um único timestamp Unix, date_parse() mantém cada parte separada e nunca descarta os diagnósticos. Essa distinção é a principal razão para utilizá-la: quando você precisa saber não apenas qual é a data, mas se a entrada era realmente uma data válida.

Esta página aborda a sintaxe, a estrutura completa do array retornado, como interpretar avisos e erros, e como date_parse() se compara a funções relacionadas.

Sintaxe

date_parse(string $datetime): array

Ela sempre retorna um array (nunca retorna false); quando a análise falha, a falha é descrita na chave errors em vez de ser sinalizada pelo valor de retorno.

Parâmetros

$datetime — uma string representando a data/hora a ser analisada. Ela aceita os mesmos formatos flexíveis compreendidos pelo parser de datas interno do PHP, por exemplo:

• '2022-03-03 15:30:45' — data e hora completas no estilo ISO
• 'July 4, 2023' — linguagem natural
• 'now', 'tomorrow', '+1 week' — expressões relativas

Se um componente estiver ausente da string (por exemplo, nenhuma hora for fornecida), sua chave é retornada com um valor vazio em vez de ser omitida.

Valor de Retorno

A função retorna um array associativo com as seguintes chaves:

• year, month, day — os componentes da data (inteiros, ou vazios se não estiverem presentes)
• hour, minute, second — os componentes de hora (inteiros, ou vazios se não estiverem presentes)
• fraction — a parte fracionária dos segundos (um float, ex.: 0)
• warning_count — o número de avisos gerados durante a análise
• warnings — um array de avisos, indexados pela posição do caractere na entrada
• error_count — o número de erros gerados durante a análise
• errors — um array de erros, indexados pela posição do caractere na entrada
• is_localtime — indica se a string continha informações de fuso horário

Quando is_localtime é true, chaves adicionais como zone_type, zone e is_dst descrevem o fuso horário.

Exemplo Básico

Vamos analisar uma string completa de data e hora:

Saída:

Array
(
    [year] => 2022
    [month] => 3
    [day] => 3
    [hour] => 15
    [minute] => 30
    [second] => 45
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

Cada componente agora está disponível individualmente — por exemplo, $date_arr['month'] é 3. Como error_count e warning_count são ambos 0, sabemos que a string era uma data válida e limpa.

Analisando uma Data Parcial

date_parse() não requer uma data completa. Se você passar apenas uma data sem hora, as chaves de hora retornam vazias:

<?php

$result = date_parse('July 4, 2023');
echo "Year: {$result['year']}\n";
echo "Month: {$result['month']}\n";
echo "Day: {$result['day']}\n";
echo "Hour: '{$result['hour']}'\n"; // empty — no time was given

Saída:

Year: 2023
Month: 7
Day: 4
Hour: ''

Isso é útil quando você aceita datas sem horas e quer as partes individuais sem precisar escrever um parser personalizado.

Detectando Datas Inválidas com Avisos

É aqui que date_parse() se destaca. Considere o dia 30 de fevereiro — uma data que não existe. O parser ainda retornará valores, mas sinalizará o problema em warnings:

<?php

$result = date_parse('2023-02-30');

if ($result['warning_count'] > 0) {
    foreach ($result['warnings'] as $position => $message) {
        echo "Warning at position $position: $message\n";
    }
}

Saída:

Warning at position 11: The parsed date was invalid

Sempre verifique error_count (a string não pôde ser compreendida de forma alguma) e warning_count (a string foi compreendida, mas descreve uma data impossível) antes de confiar nos componentes analisados. Para uma verificação estrita de sim/não no calendário para um ano-mês-dia específico, combine isso com checkdate().

Quando Usar date_parse() vs. Funções Relacionadas

Se você precisar renderizar uma data posteriormente, veja date() para formatar os componentes em uma string.

Conclusão

A função date_parse() fornece uma maneira direta de decompor uma string de data em seus componentes individuais enquanto reporta quaisquer avisos e erros ao longo do processo. Esse papel duplo — extração e validação — a torna especialmente útil para verificar datas fornecidas pelo usuário antes de processá-las. Combine-a com checkdate() para validação estrita, ou com strtotime() e DateTime quando você precisar de timestamps ou objetos de data completos.

Prática