php/archived-doc-pt-br
1
0
Fork 0
mirror of https://github.com/php/doc-pt_br.git synced 2026-03-23 22:52:12 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
452d861bfbdf0fee2b8af13a8c0e20ca0376ac99
archived-doc-pt-br/reference/datetime/datetimeimmutable/createfromformat.xml
Leonardo Lara Rodrigues 452d861bfb sync with en rev
2025-11-04 18:29:39 -03:00

813 lines
30 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: cafec7df4c6ba597b5ac45b03191aea18f3cabab Maintainer: leonardolara Status: ready --><!-- CREDITS: fabioluciano, leonardolara -->
<refentry xml:id="datetimeimmutable.createfromformat" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>DateTimeImmutable::createFromFormat</refname>
<refname>date_create_immutable_from_format</refname>
<refpurpose>Interpreta um string de data/horário de acordo com o formato especificado</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>DateTimeImmutable</type><type>false</type></type><methodname>DateTimeImmutable::createFromFormat</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<type class="union"><type>DateTimeImmutable</type><type>false</type></type><methodname>date_create_immutable_from_format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Retorna um novo objeto DateTimeImmutable representando a data e o horário especificados pelo
string <parameter>datetime</parameter>, formatado pelo parâmetro
<parameter>format</parameter>.
</para>
</refsect1>
<refsect1 role="parameters" xml:id="datetimeimmutable.createfromformat.parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
O formato no qual a <type>string</type> passada deve estar. Veja as
opções de formatação abaixo. Na maioria dos casos, as mesmas letras da
função <function>date</function> podem ser usadas.
</para>
<para>
Todos os campos são inicializados com a data/horário atual. Na maioria das vezes,
a intenção pode ser "zerá-los" (época Unix, <literal>1970-01-01
00:00:00 UTC</literal>). Isto pode ser feito incluindo o
caractere <literal>!</literal> como o primeiro no
parâmetro <parameter>format</parameter>, ou <literal>|</literal> como o último.
Favor verificar a documentação para cada caractere abaixo para mais
informação.
</para>
<para>
O formato é analisado da esquerda para a direita, o que significa que em algumas
situações a ordem na qual os caracteres de formato estão presents afeta
o resultado. No caso de <literal>z</literal> (o dia do ano),
é necessário que um ano já tenha sido analisado,
por exemplo através dos caracteres <literal>Y</literal> ou
<literal>y</literal>.
</para>
<para>
Letras que são usadas para representar números permitem uma ampla gama de valores,
fora do que seria a faixa lógica. Por exemplo, a letra
<literal>d</literal> (dia do mês) aceita valores na faixa de
<literal>00</literal> a <literal>99</literal>. A única restrição é
o número de dígitos. O mecanismo de overflow do analisador é
usado quando valores fora da faixa são especificados. Os exemplos abaixo mostram alguns
destes comportamentos.
</para>
<para>
Isto também significa que os dados analisados para um caractere de formatação são ambiciosos, e
irão ler até a quantidade de dígitos que o formato permite. Isto pode
também então significar que não há mais
caracteres suficientes na string do parâmetro <parameter>datetime</parameter>
para os caracteres de formato seguintes. Um exemplo nesta página também
ilustra este problema.
</para>
<para>
<table>
<title>Os seguintes caracteres são reconhecidos na
string do parâmetros <parameter>format</parameter></title>
<tgroup cols="3">
<thead>
<row>
<entry>Caractere de <parameter>format</parameter></entry>
<entry>Descrição</entry>
<entry>Exemplo de valores analisáveis</entry>
</row>
</thead>
<tbody>
<row>
<entry align="center"><emphasis>Dia</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>d</literal> e <literal>j</literal></entry>
<entry>Dia do mês, 2 dígitos com ou sem zeros na frente</entry>
<entry>
<literal>01</literal> a <literal>31</literal> ou
<literal>1</literal> a <literal>31</literal>. (números de 2 dígitos
maiores queo número de dias no mês são aceitos, e neste caso
irão causar uma transferência no mês. Por exemplo, usar 33 com
janeiro, significa 2 de fevereiro)
</entry>
</row>
<row>
<entry><literal>D</literal> e <literal>l</literal></entry>
<entry>Uma representação textual de um dia</entry>
<entry>
<literal>Mon</literal> a <literal>Sun</literal> ou
<literal>Sunday</literal> a <literal>Saturday</literal>. Se
o nome do dia informado for diferente do nome do dia pertencente a
uma data analisada (ou data padrão), então uma transferência ocorre para
a <emphasis>próxima</emphasis> data com o nome do dia informado. Veja os
exemplos abaixo para uma explicação.
</entry>
</row>
<row>
<entry><literal>S</literal></entry>
<entry>Sufixo em inglês para o ordinal do dia do mês, 2
caracteres. É ignorado durante o processamento.</entry>
<entry>
<literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> ou
<literal>th</literal>.
</entry>
</row>
<row>
<entry><literal>z</literal></entry>
<entry>
O dia do ano (iniciando em 0);
deve ser precedido de <literal>Y</literal> ou <literal>y</literal>.
</entry>
<entry>
<literal>0</literal> a <literal>365</literal>. (números de 3 dígitos
maiores que o número de dias em um ano são aceitos, e neste
caso case irão causar uma transferência de ano. Por exemplo, usar 366 com
2022, significa 2 de janeiro de 2023)
</entry>
</row>
<row>
<entry align="center"><emphasis>Mês</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>F</literal> e <literal>M</literal></entry>
<entry>Uma representação textual do mês, como January ou Sept</entry>
<entry>
<literal>January</literal> a <literal>December</literal> ou
<literal>Jan</literal> a <literal>Dec</literal>
</entry>
</row>
<row>
<entry><literal>m</literal> e <literal>n</literal></entry>
<entry>Representação numérica de um mês, com ou sem zeros na frente</entry>
<entry>
<literal>01</literal> a <literal>12</literal> ou
<literal>1</literal> a <literal>12</literal>.
(números de 2 dígitos maiores que 12 são aceitos, e neste caso eles
irão causar uma transferência de ano. Por exemplo, usar 13 significa janeiro do
ano seguinte)
</entry>
</row>
<row>
<entry align="center"><emphasis>Ano</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>X</literal> e <literal>x</literal></entry>
<entry>Uma representação numérica completa de um ano, <emphasis>com até</emphasis> 19 dígitos,
opcionalmente prefixada por <literal>+</literal> ou
<literal>-</literal></entry>
<entry>Exemplos: <literal>0055</literal>, <literal>787</literal>,
<literal>1999</literal>, <literal>-2003</literal>,
<literal>+10191</literal></entry>
</row>
<row>
<entry><literal>Y</literal></entry>
<entry>Uma representação numérica completa de um ano, <emphasis>com até</emphasis> 4 dígitos</entry>
<entry>Exemplos: <literal>25</literal> (o mesmo que <literal>0025</literal>),
<literal>787</literal>, <literal>1999</literal>, <literal>2003</literal></entry>
</row>
<row>
<entry><literal>y</literal></entry>
<entry>
Uma representação de dois dígitos de um ano (que assume-se estar na faixa
1970-2069, inclusive)
</entry>
<entry>
Exemplos:
<literal>99</literal> ou <literal>03</literal>
(que será interpretado como <literal>1999</literal> e
<literal>2003</literal>, respectivamente)
</entry>
</row>
<row>
<entry align="center"><emphasis>Horário</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>a</literal> e <literal>A</literal></entry>
<entry>Ante meridiem e Post meridiem</entry>
<entry><literal>am</literal> ou <literal>pm</literal></entry>
</row>
<row>
<entry><literal>g</literal> e <literal>h</literal></entry>
<entry>Formato de 12 horas para uma hora com ou sem zeros na frente</entry>
<entry>
<literal>1</literal> a <literal>12</literal> ou
<literal>01</literal> a <literal>12</literal> (números de 2 dígitos
maiores que 12 são aceitos, e neste caso eles irão
causar uma transferência de período AM/PM. Por exemplo, usar <literal>14</literal> significa
<literal>02</literal> no próximo período AM/PM)
</entry>
</row>
<row>
<entry><literal>G</literal> e <literal>H</literal></entry>
<entry>Formato de 24 horas para uma hora com ou sem zeros na frente</entry>
<entry>
<literal>0</literal> a <literal>23</literal> ou
<literal>00</literal> a <literal>23</literal> (números de 2 dígitos
maiores que 24 são aceitos, e neste caso eles irão causar
uma transferência de dia. Por exemplo, usar <literal>26</literal> significa
<literal>02:00</literal> do dia seguinte)
</entry>
</row>
<row>
<entry><literal>i</literal></entry>
<entry>Minutos com zero na frente</entry>
<entry>
<literal>00</literal> a <literal>59</literal>. (números de 2 dígitos
maiores que 59 são aceitos, e neste caso irão causar
uma transferência de hora. Por exemplo, usar <literal>66</literal> significa
<literal>:06</literal> da hora seguinte)
</entry>
</row>
<row>
<entry><literal>s</literal></entry>
<entry>Segundos, com zero na frente</entry>
<entry>
<literal>00</literal> a <literal>59</literal> (números de 2 dígitos
maiores que 59 são aceitos, e neste caso irão causar
uma transferência de minuto. Por exemplo, usar <literal>90</literal> significa
<literal>:30</literal> do próximo minuto)
</entry>
</row>
<row>
<entry><literal>v</literal></entry>
<entry>Fração em milissegundos (até três dígitos)</entry>
<entry>Exemplo: <literal>12</literal> (<literal>0.12</literal>
segundo), <literal>345</literal> (<literal>0.345</literal> segundo)</entry>
</row>
<row>
<entry><literal>u</literal></entry>
<entry>Fração em microssegundos (até seis dígitos)</entry>
<entry>Exemplo: <literal>45</literal> (<literal>0.45</literal>
segundo) <literal>654321</literal> (<literal>0.654321</literal>
segundo)</entry>
</row>
<row>
<entry align="center"><emphasis>Fuso horário</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry>
<literal>e</literal>, <literal>O</literal>, <literal>p</literal>,
<literal>P</literal> e <literal>T</literal>
</entry>
<entry>Identificador do fuso horário, ou a diferença para UTC em horas, ou
a diferença para UTC com dois pontos entre horas e minutos, ou
abreviação do fuso horário</entry>
<entry>Exemplos: <literal>UTC</literal>, <literal>GMT</literal>,
<literal>Atlantic/Azores</literal> ou
<literal>+0200</literal> ou <literal>+02:00</literal> ou
<literal>EST</literal>, <literal>MDT</literal>
</entry>
</row>
<row>
<entry align="center"><emphasis>Data/Horário completos</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>U</literal></entry>
<entry>Segundos desde a Época Unix (1 janeiro 1970 00:00:00 GMT)</entry>
<entry>Exemplo: <literal>1292177455</literal></entry>
</row>
<row>
<entry align="center"><emphasis>Espaços em branco e separadores</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal> </literal> (espaço)</entry>
<entry>Zero ou mais espaços, tabulações, caracteres NBSP (U+A0),
ou NNBSP (U+202F)</entry>
<entry>Exemplo: <literal>"\t"</literal>, <literal>" "</literal></entry>
</row>
<row>
<entry><literal>#</literal></entry>
<entry>
Um dos símbolos de separação: <literal>;</literal>,
<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
<literal>,</literal>, <literal>-</literal>, <literal>(</literal> ou
<literal>)</literal>
</entry>
<entry>Exemplo: <literal>/</literal></entry>
</row>
<row>
<entry>
<literal>;</literal>,
<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
<literal>,</literal>, <literal>-</literal>, <literal>(</literal> ou
<literal>)</literal>
</entry>
<entry>O caractere especificado.</entry>
<entry>Exemplo: <literal>-</literal></entry>
</row>
<row>
<entry><literal>?</literal></entry>
<entry>Um byte aleatório</entry>
<entry>Exemplo: <literal>^</literal> (Esteja ciente que para caracteres UTF-8
pode ser necessário mais de um <literal>?</literal>.
Neste caso, usar <literal>*</literal> pode ser o o mais
adequado na verdade)</entry>
</row>
<row>
<entry><literal>*</literal></entry>
<entry>Bytes aleatórios até o próximo separador ou dígito</entry>
<entry>Exemplo: <literal>*</literal> em <literal>Y-*-d</literal> com
o string <literal>2009-aWord-08</literal> será equivalente a
<literal>aWord</literal></entry>
</row>
<row>
<entry><literal>!</literal></entry>
<entry>Reconfigura todos os campos (ano, mês, dia, hora, minuto, segundo,
fração e informação de fuso horário) com valores tipo zero (
<literal>0</literal> para hora, minuto, segundo e fração,
<literal>1</literal> para mês e dia, <literal>1970</literal>
para ano e <literal>UTC</literal> para informação de fuso horário)</entry>
<entry>Sem <literal>!,</literal> todos os campos serão configurados com a
data/horário atual.</entry>
</row>
<row>
<entry><literal>|</literal></entry>
<entry>Reconfigura todos os campos (ano, mês, dia, hora, minuto, segundo,
fração e informação de fuso horário) com valores tipo zero se eles
ainda não foram analisados</entry>
<entry><literal>Y-m-d|</literal> irá configurar o ano, mês e dia
para as informações encontradas na string a ser analisada, e configura a hora,
minuto e segundo para 0.</entry>
</row>
<row>
<entry><literal>+</literal></entry>
<entry>Se esta especificação de formato estiver presente, dados no final da
string não irão causar um erro, mas sim um aviso</entry>
<entry>Use <methodname>DateTimeImmutable::getLastErrors</methodname> para descobrir
se dados no final da string estavam presentes.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Caracteres não reconhecidos na string de formatação irão causar
falha na análise e uma mensagem de erro será anexada na estrutura
retornada. É possível recuperar a mensagem de erro com
<methodname>DateTimeImmutable::getLastErrors</methodname>.
</para>
<para>
Para incluir caracteres literais no parâmetro <parameter>format</parameter>, deve-se
usar a barra invertida (<literal>\</literal>) antes deles.
</para>
<para>
Se <parameter>format</parameter> não contiver o caractere
<literal>!</literal> então partes da data/horário gerada que não foram
especificadas em <parameter>format</parameter> serão configuradas para a
data/horário atual do sistema.
</para>
<para>
Se <parameter>format</parameter> contiver o
caractere <literal>!</literal>, então partes da data/horário
gerada não especificada em <parameter>format</parameter>, assim como
valores à esquerda de <literal>!</literal>, serão
configuradas aos valores correspondentes da época Unix.
</para>
<para>
Se algum caractere de horário for analisado, então todos os outros campos relacionados a horário são
configurados para "0", a menos que também tenham sido analisados.
</para>
<para>
A Época Unix é 1970-01-01 00:00:00 UTC.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<para>
String representando a data/horário.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>timezone</parameter></term>
<listitem>
<para>
Um objeto <classname>DateTimeZone</classname> representando o
fuso horário desejado.
</para>
<para>
Se <parameter>timezone</parameter> for &null; ou omitido e
<parameter>datetime</parameter> não contém o fuso horário,
o fuso atual será usado.
</para>
<note>
<para>
O parâmetro <parameter>timezone</parameter>
e o fuso horário atual são ignorados quando o parâmetro
<parameter>datetime</parameter> contém
um timestamp UNIX (ex.: <literal>946684800</literal>)
ou especifica um fuso horário
(ex.: <literal>2010-01-28T15:00:00+02:00</literal>).
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Retorna uma nova instância de DateTimeImmutable&return.falseforfailure;.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Este método lança uma exceção <exceptionname>ValueError</exceptionname> quando o
parâmetro <parameter>datetime</parameter> contiver bytes nulos.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.2.9</entry>
<entry>
O especificador <literal> </literal> (space) agora também suporta caracteres NBSP
(U+A0) e NNBSP (U+202F).
</entry>
</row>
<row>
<entry>8.2.0</entry>
<entry>
Os especificadores <literal>X</literal> e <literal>x</literal> de
<parameter>format</parameter> foram adicionados.
</entry>
</row>
<row>
<entry>8.0.21, 8.1.8, 8.2.0</entry>
<entry>
Agora lança a exceção <exceptionname>ValueError</exceptionname> quando bytes nulos
são passados no parâmetro <parameter>datetime</parameter>, o que antes era silenciosamente
ignorado.
</entry>
</row>
<row>
<entry>7.3.0</entry>
<entry>
O especificador <literal>v</literal> em <parameter>format</parameter> foi
adicionado.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Exemplo de <function>DateTimeImmutable::createFromFormat</function></title>
<para>&style.oop;</para>
<programlisting role="php">
<![CDATA[
<?php
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
]]>
</programlisting>
</example>
<example>
<title>Usando constantes predefinidas de formato com <function>DateTimeImmutable::createFromFormat</function></title>
<para>&style.oop;</para>
<programlisting role="php">
<![CDATA[
<?php
$date = DateTimeImmutable::createFromFormat(
DateTimeInterface::ISO8601,
'2004-02-12T15:19:21+00:00'
);
echo $date->format('c e') . "\n";
$date = DateTimeImmutable::createFromFormat(
DateTimeInterface::RFC3339_EXTENDED,
'2013-10-14T09:00:00.000+02:00'
);
echo $date->format('c e') . "\n";
]]>
</programlisting>
<para>
As <link linkend="datetimeinterface.constants.types">constantes de formatação</link>
como usadas neste exemplo consistem de
uma string de caracteres para <link linkend="datetime.format">formatar</link> um
objeto <classname>DateTimeImmutable</classname>. Na maioria dos casos, estas
letras são equivalentes aos elementos de data/horário definidos na seção <link
linkend="datetimeimmutable.createfromformat.parameters">parameters</link>
acima, mas elas tendem a ser mais lenientes.
</para>
</example>
<example>
<title>Complexidades de <function>DateTimeImmutable::createFromFormat</function></title>
<programlisting role="php">
<![CDATA[
<?php
echo 'Horário atual: ' . date('Y-m-d H:i:s') . "\n";
$format = 'Y-m-d';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = 'Y-m-d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = 'Y-m-!d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = '!d';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";
$format = 'i';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Horário atual: 2022-06-02 15:50:46
Formato: Y-m-d; 2009-02-15 15:50:46
Formato: Y-m-d H:i:s; 2009-02-15 15:16:17
Formato: Y-m-!d H:i:s; 1970-01-15 15:16:17
Formato: !d; 1970-01-15 00:00:00
Formato: i; 2022-06-02 00:15:00
]]>
</screen>
</example>
<example>
<title>String de formatação com caracteres literais</title>
<programlisting role="php">
<![CDATA[
<?php
echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
23:15:03
]]>
</screen>
</example>
<example>
<title>Comportamento de transferência</title>
<programlisting role="php">
<![CDATA[
<?php
echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Sat, 04 Jun 2022 17:01:37 +0000
]]>
</screen>
<para>
Embora o resultado pareça estranho, ele está correto, já que as transferências abaixo
ocorrem:
</para>
<orderedlist>
<listitem>
<simpara>
<literal>97</literal> segundos transferem para <literal>1</literal> minuto,
sobrando <literal>37</literal> segundos.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>61</literal> minutos transferem para <literal>1</literal> hora,
sobrando <literal>1</literal> minuto.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>35</literal> dias transferem para <literal>1</literal> mês,
sobrando <literal>4</literal> dias. A quantidade de dias que sobram
depende do mês, já que nem todo mês tem o mesmo número de dias.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>18</literal> meses transferem para <literal>1</literal> ano,
sobrando <literal>6</literal> meses.
</simpara>
</listitem>
</orderedlist>
</example>
<example>
<title>Comportamento de transferência do nome do dia</title>
<programlisting role="php">
<![CDATA[
<?php
$d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
echo $d->format(DateTime::RFC1123), "\n";
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Mon, 10 Aug 2020 01:00:00 +0000
]]>
</screen>
<para>
Embora o resultado pareça estranho, ele está correto, já que as transferências abaixo
ocorrem:
</para>
<orderedlist>
<listitem>
<simpara>
<literal>3 Aug 2020 25:00:00</literal> transfere para <literal>(Tue) 4 Aug
2020 01:00</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>Mon</literal> é aplicado, o que avança a data para
<literal>Mon, 10 Aug 2020 01:00:00</literal>. A explicação para
as palavras-chaves relativas como <literal>Mon</literal> está disponível na
seção sobre <link linkend="datetime.formats.relative">formatos
relativos</link>.
</simpara>
</listitem>
</orderedlist>
</example>
<para>
Para detectar transferências em datas/horas, pode-se usar
o método <methodname>DateTimeImmutable::getLastErrors</methodname>, que irá
incluir um aviso se uma transferência tiver ocorrido.
</para>
<example>
<title>Detectando transferência de datas/horas</title>
<programlisting role="php">
<![CDATA[
<?php
$d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
echo $d->format(DateTimeImmutable::RFC2822), "\n\n";
var_dump(DateTimeImmutable::getLastErrors());
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Sat, 04 Jun 2022 17:01:37 +0000
array(4) {
'warning_count' =>
int(2)
'warnings' =>
array(1) {
[19] =>
string(27) "The parsed date was invalid"
}
'error_count' =>
int(0)
'errors' =>
array(0) {
}
}
]]>
</screen>
</example>
<example>
<title>Comportamento de análise ambicioso</title>
<programlisting role="php">
<![CDATA[
<?php
print_r(date_parse_from_format('Gis', '60101'));
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
[year] =>
[month] =>
[day] =>
[hour] => 60
[minute] => 10
[second] => 0
[fraction] => 0
[warning_count] => 1
[warnings] => Array
(
[5] => The parsed time was invalid
)
[error_count] => 1
[errors] => Array
(
[4] => A two digit second could not be found
)
[is_localtime] =>
)
]]>
</screen>
<para>
O formato <literal>G</literal> analisa horas no formato de 24 horas, com ou
sem zeros na frente. Isto requer analisar 1 ou 2 dígitos. Como há
dois dígitos disponíveis, o analisador ambiciosamente lê o valor como <literal>60</literal>.
</para>
<para>
Os caracteres seguintes <literal>i</literal> e <literal>s</literal>
ambos requerem dois dígitos. Isto significa que <literal>10</literal>
é passado como minutos (<literal>i</literal>), e que não há então
dígitos suficientes restantes para serem analisados como segundos (<literal>s</literal>).
</para>
<para>
O array <literal>errors</literal> indica este problema.
</para>
<para>
Adicionalmente, um valor de hora de <literal>60</literal> está fora da faixa
<literal>0</literal>-<literal>24</literal>, o que faz com que o array de
<literal>warnings</literal> inclua um aviso de que o horário é
inválido.
</para>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>DateTimeImmutable::__construct</function></member>
<member><function>DateTimeImmutable::getLastErrors</function></member>
<member><function>checkdate</function></member>
<member><function>strptime</function></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Reference in New Issue View Git Blame Copy Permalink