Retorna um array associativo com informações detalhadas da data/horário informada

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Retorna um array associativo com informações detalhadas da data/horário informada

### Descrição

function date_parse(string `$datetime`): array

A função date_parse() analisa a string `datetime` informada conforme as mesmas regras de strtotime() e DateTimeImmutable::__construct(). Ao invés de retornar um timestamp Unix (com strtotime()) ou objeto DateTimeImmutable (com a função DateTimeImmutable::__construct()), ela retorna um array associativo com a informação que ela poderia detectar na string `datetime` fornecida.

Se nenhuma informação sobre um certo grupo de elementos puder ser encontrada, estes elementos do array serão configurados para `false` ou omitidos. Se necessário para construção de um timestamp ou objeto DateTimeImmutable a partir da mesma string `datetime`, mais campos podem ser configurados para um valor não-`false`. Veja os exemplos para casos onde isso acontece..

### Parâmetros

`datetime`

  Data/horário no formato aceito pela função DateTimeImmutable::__construct().

### Valor Retornado

Retorna um array com informações da data/horário analisada.

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.

Se elementos de tempo relativo estiverem presentes na string `datetime` como `+3 days`, então o array retornado incluirá um array aninhado com a chave `relative`. Este array então conterá as chaves `year`, `month`, `day`, `hour`, `minute`, `second`, e se necessário `weekday` e `weekdays`, dependendo da string que foi passada.

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.

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.

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

Se o formato da data/horário contiver erro, o elemento 'errors' conterá as mensagens de erro.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | O elemento `zone` do array de retorno agora representa segundos no lugar de minutos, e seu sinal é invertido. Por exemplo, `-120` é agora `7200`.

### Exemplos

Exemplo #1 Um exemplo da função date_parse()com um string `datetime` compreensivo

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

O exemplo acima produzirá:

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Os elementos de fuso horário só aparecem se eles forem incluídos no parâmetro `datetime`. Neste caso sempre haverá um elemento `zone_type` e alguns mais dependendo do seu valor.

Exemplo #2 Exemplo da função date_parse() com informação de abreviação de fuso horário

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

O exemplo acima produzirá:

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Exemplo #3 Exemplo da função date_parse() com informação de identificador de fuso horário

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

O exemplo acima produzirá:

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

Se uma string mais enxuta de `datetime` for analisada, menos informação estará disponível. Neste exemplo, todas as partes de horário são retornadas como `false`.

Exemplo #4 Função date_parse() com um string minimizado

    <?php
    var_dump(date_parse("June 2nd, 2022"));

O exemplo acima produzirá:

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Formatos relativos não influenciam valores interpretados de formatos absolutos, mas são analisados no elemento "relative".

Exemplo #5 date_parse() com formatos relativos

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

O exemplo acima produzirá:

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Algumas strings, como `Thursday` por exemplo, irão configurar a parte de horário da string para `0`. Se `Thursday` for passado para a função DateTimeImmutable::__construct(), ela também teria resultado em hora, minuto, segundo e fração configurados para `0`. No exemplo abaixo, o elemento do ano também é configurado como `false`.

Exemplo #6 Função date_parse() com efeitos colaterais

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

O exemplo acima produzirá:

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Veja Também

- date_parse_from_format() - Retorna informações sobre uma data informada de acordo com um formato para analisar um `datetime` com um formato específico
- checkdate() - Valida uma data gregoriana para validação da data do calendário gregoriano
- getdate() - Recupera informações de data/horário

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open