archived-doc-pt-br/reference/datetime/functions/date.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 3a8c3e77df070a046c9d5b56b68926ca2d7e5ee3 Maintainer: leonardolara Status: ready --><!-- CREDITS: surfmax, thiago, fabioluciano, rogeriopradoj, lhsazevedo, leonardolara -->
<refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>date</refname>
  <refpurpose>Formata um timestamp Unix</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>date</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>timestamp</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Retorna uma string de acordo com a string de formato informada usando o
   inteiro <parameter>timestamp</parameter> (timestamp Unix) informado, ou o horário local atual
   se nenhum timestamp for informado. Em outras palavras, o parâmetro <parameter>timestamp</parameter>
   é opcional e padronizado para o valor de <function>time</function>.
  </para>
  <warning>
   <para>
    Timestamps Unix não lidam com fusos horários. Use a
    classe <classname>DateTimeImmutable</classname> e seu
    método de formatação <methodname>DateTimeInterface::format</methodname> para
    formatar informações de data/horário com um fuso horário anexado.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>format</parameter></term>
    <listitem>
     <para>
      Formato aceito pelo <methodname>DateTimeInterface::format</methodname>.
     </para>
      <note>
       <simpara>
        <function>date</function> irá sempre gerar
        <literal>000000</literal> para os microssegundos já que ele usa um parâmetro <type>int</type>,
        enquanto que <methodname>DateTimeInterface::format</methodname>
        suporta microssegundos se um objeto do tipo
        <interfacename>DateTimeInterface</interfacename> foi criado com microssegundos.
       </simpara>
      </note>
    </listitem>
   </varlistentry>

   &date.timestamp.description;

  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retorna uma string formatada de data.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;

   &date.timezone.errors.description;

 </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.0.0</entry>
       <entry>
        <parameter>timestamp</parameter> agora pode ser nulo.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemplos da função <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Modifica o fuso horário a ser utilizado.
date_default_timezone_set('UTC');


// Exibe algo coisa como: Monday
echo date("l") . "\n";

// Exibe algo como: Monday 8th of August 2005 03:12:46 PM
echo date('l jS \of F Y h:i:s A') . "\n";

// Exibe: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

/* Utiliza as constantes do parâmetro de formato */
// Exibe algo como: Mon, 15 Aug 2005 15:12:46 UTC
echo date(DATE_RFC2822) . "\n";

// Exibe algo como: 2000-07-01T00:00:00+00:00
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Para evitar que um caractere reconhecido na string de formatação seja
   expandido, prefixe-o com uma barra invertida. Se o caractere com a
   barra invertida já for uma sequência especial, pode ser necessário também prefixá-lo com a
   barra invertida.
   <example>
    <title>Caracteres de escape em <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Exibe algo como: Wednesday the 15th
echo date("l \\t\h\e jS");
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Alguns exemplos de formatação de <function>date</function>. Observe que
   qualquer outro caractere deve ser escapado, pois qualquer um que possua
   um significado especial produzirá resultados indesejáveis,
   e outros caracteres podem assumir significado em futuras versões do PHP.
   Quando usar escape, certifique-se de usar aspas simples para evitar que caracteres
   como \n virem novas linhas.
   <example>
    <title>Formatação com a função <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// Assumindo que hoje é dia 10 de março de 2001, 17:16:18, e que estamos no
// fuso horário Mountain Standard Time (MST)
date_default_timezone_set("America/Phoenix");

$today = date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
$today = date("m.d.y") . "\n";                         // 03.10.01
$today = date("j, n, Y") . "\n";                       // 10, 3, 2001
$today = date("Ymd") . "\n";                           // 20010310
$today = date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
$today = date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
$today = date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
$today = date("H:i:s") . "\n";                         // 17:16:18
$today = date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (o formato DATETIME do MySQL)
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Para formatar datas em outros idiomas,
   <methodname>IntlDateFormatter::format</methodname>
   pode ser utilizada em vez de <function>date</function>.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Para gerar um timestamp de uma string da representação da data,
    pode-se utilizar as funções <function>strtotime</function>. Adicionalmente, alguns
    banco de dados tem funções para converter os formatos de data para
    timestamps (como a função <link
    xlink:href="&url.mysql.docs.date;">UNIX_TIMESTAMP</link> do MySQL).
   </para>
  </note>
  <tip>
   <para>
    O timestamp do início da requisição está disponível na variável
    <varname>$_SERVER['REQUEST_TIME']</varname>.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>DateTimeImmutable::__construct</methodname></member>
    <member><methodname>DateTimeInterface::format</methodname></member>
    <member><function>gmdate</function></member>
    <member><function>idate</function></member>
    <member><function>getdate</function></member>
    <member><function>getlastmod</function></member>
    <member><function>mktime</function></member>
    <member><methodname>IntlDateFormatter::format</methodname></member>
    <member><function>time</function></member>
    <member><link linkend="datetimeinterface.constants.types">Constantes Predefinidas da Classe DateTime</link></member>
   </simplelist>
  </para>
 </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
-->