Descrição

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

Retorna um array associativo com informação detalhada sobre a data/horário informada.

Parâmetros

format: Para documentação sobre como o parâmetro format é usado, favor se referir à documentação da função DateTimeImmutable::createFromFormat(). As mesmas regras se aplicam.
datetime: String que representa a data/horário.

Valor Retornado

Retorna um array associativo com informação detalhada da data/horário informada.

O array de retorno tem chaves para year, month, day, hour, minute, second, fraction, e is_localtime.

Se is_localtime estiver presente então zone_type indica o tipo do fuso horário. Para o tipo 1 (deslocamento UTC), os campos zone e is_dst são incluídos; para o tipo 2 (abreviação), os campos tz_abbr e is_dst são incluídos; e para tipo 3 (identificador de fuso), os campos tz_abbr e tz_id são incluídos.

O array inclui os campos warning_count e warnings. O primeiro indica quantos avisos ocorreram. As chaves dos elementos do array warnings indicam as posições na string datetime onde os avisos ocorreram, com o valor da string descrevendo o aviso em si. Um exemplo abaixo mostra tal aviso.

O array também contém os campos error_count e errors. O primeiro indica quantos erros foram encontrados. As chaves dos elementos do array errors indicam posição na string datetime onde os erros ocorreram, com o valor da string descrevendo o erro em si. Um exemplo abaixo mostra tal erro.

Aviso

O número de elementos do arrays warnings ou errors pode ser menor que warning_count ou error_count se eles ocorreram na mesma posição.

Erros/Exceções

Esta função dispara a exceção ValueError quando o parâmetro datetime contém bytes nulos.

Registro de Alterações

Versão	Descrição
8.0.21, 8.1.8, 8.2.0	Agora lança ValueError quando bytes nulos são passados por `datetime`, o que antes era silenciosamente ignorado.
7.2.0	O elemento `zone` do array retornado agora representa segundos em vez de minutos, e seu sinal é invertido. Por exemplo, `-120` agora é `7200`.

Exemplos

Exemplo #1 Exemplo da função date_parse_from_format()

<?php
$date = "6.1.2009 13:00+01:00";
print_r(date_parse_from_format("j.n.Y H:iP", $date));

O exemplo acima produzirá:

Array
(
    [year] => 2009
    [month] => 1
    [day] => 6
    [hour] => 13
    [minute] => 0
    [second] => 0
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array
        (
        )

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

    [is_localtime] => 1
    [zone_type] => 1
    [zone] => 3600
    [is_dst] =>
)

Exemplo #2 Exemplo da função date_parse_from_format() com avisos

<?php
$date = "26 August 2022 22:30 pm";
$parsed = date_parse_from_format("j F Y G:i a", $date);

echo "Contagem de avisos: ", $parsed['warning_count'], "\n";
foreach ($parsed['warnings'] as $position => $message) {
    echo "\tNa posição {$position}: {$message}\n";
}

O exemplo acima produzirá:

Contagem de avisos: 1
Na posição 23: The parsed time was invalid

Exemplo #3 Exemplo da função date_parse_from_format() com erros

<?php
$date = "26 August 2022 CEST";
$parsed = date_parse_from_format("j F Y H:i", $date);

echo "Contagem de erros: ", $parsed['error_count'], "\n";
foreach ($parsed['errors'] as $position => $message) {
    echo "\tNa posição {$position}: {$message}\n";
}

O exemplo acima produzirá:

Contagem de erros: 3
Na posição 15: A two digit hour could not be found
Na posição 19: Not enough data available to satisfy format

Veja Também

DateTimeImmutable::createFromFormat() - Interpreta um string de data/horário de acordo com o formato especificado
checkdate() - Valida uma data gregoriana