archived-doc-ru/reference/datetime/functions/date.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 3a8c3e77df070a046c9d5b56b68926ca2d7e5ee3 Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>date</refname>
  <refpurpose>Форматирует метку времени эпохи 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>
   Функция возвращает отформатированную по заданной строке формата строку с датой и (или) временем,
   которую сгенерировала на основе параметра <parameter>timestamp</parameter> —
   целочисленной метки Unix-времени,
   которую передали в функцию или которую функция получила на основе текущего системного времени,
   если метку времени не передали. Поэтому параметр <parameter>timestamp</parameter>
   необязателен и по умолчанию равен значению, которое возвращает
   функция <function>time</function>.
  </para>
  <warning>
   <para>
    Метки времени Unix не обрабатывают часовые пояса.
    Информацию о дате и времени с прикреплённым часовым поясом
    форматируют методом <methodname>DateTimeInterface::format</methodname>
    класса <classname>DateTimeImmutable</classname>.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>format</parameter></term>
    <listitem>
     <para>
      Формат, который принимается методом <methodname>DateTimeInterface::format</methodname>.
     </para>
     <note>
      <simpara>
       Функция <function>date</function> генерирует для поля микросекунд
       значение <literal>000000</literal>, поскольку принимает метку времени
       как целочисленное (int) значение в секундах, тогда как метод
       <methodname>DateTimeInterface::format</methodname> поддерживает микросекунды,
       если объект <interfacename>DateTimeInterface</interfacename> создали с микросекундами.
      </simpara>
     </note>
    </listitem>
    </varlistentry>

    &date.timestamp.description;

  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Функция возвращает отформатированную строку с датой.
  </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> теперь принимает значение null.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Примеры использования функции <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php

// Установка часового пояса по умолчанию
date_default_timezone_set('UTC');


// Выведет что-то наподобие: Monday
echo date("l") . "\n";

// Выведет что-то наподобие: Monday 8th of August 2005 03:12:46 PM
echo date('l jS \of F Y h:i:s A') . "\n";

// Выведет: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

/* Пример константы в параметре format */
// Выведет что-то наподобие: Mon, 15 Aug 2005 15:12:46 UTC
echo date(DATE_RFC822) . "\n";

// Выведет что-то наподобие: 2000-07-01T00:00:00+00:00
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Разворачивание символа в строке формата, который распознал метод,
   останавливают путём экранирования символа форматирования обратным слешем.
   Иногда требуется заэкранировать сам обратный слеш, если символ с обратным слешем
   образует управляющую последовательность.
   <example>
    <title>Экранирование символов в функции <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php

// Выведет что-то наподобие: Wednesday the 15th
echo date('l \t\h\e jS');
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Приведём ещё ряд примеров форматирования даты функцией <function>date</function>.
   Обратите внимание: каждый символ, которым не планировалось форматировать время,
   экранируется, поскольку символы со значением форматирования дадут нежелательный результат,
   если функция встретит такие символы там, где требовалось вывести сам символ,
   а другим символам могут назначить свойства форматирования в следующих версиях PHP.
   При экранировании указывают одинарные кавычки, чтобы символы наподобие \n
   не превращались в символы новой строки.
   <example>
    <title>Пример форматирования даты функцией <function>date</function></title>
    <programlisting role="php">
<![CDATA[
<?php

// Предположим, что сегодня 10 марта 2001 и 5:16:18 вечера
// в часовом поясе Mountain Standard Time (MST)
date_default_timezone_set("America/Phoenix");

echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
echo date("m.d.y") . "\n";                         // 03.10.01
echo date("j, n, Y") . "\n";                       // 10, 3, 2001
echo date("Ymd") . "\n";                           // 20010310
echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
echo date("H:i:s") . "\n";                         // 17:16:18
echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (the MySQL DATETIME format)
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Даты на других языках вместо функции <function>date</function>
   форматируют методом <methodname>IntlDateFormatter::format</methodname>.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Метку времени из строкового представления даты генерируют
    функцией <function>strtotime</function>. Кроме того, в отдельных базах данных есть
    функции для преобразования внутреннего представления даты в метки времени
    (например, функция <link xlink:href="&url.mysql.docs.date;">UNIX_TIMESTAMP</link> БД MySQL).
   </para>
  </note>
  <tip>
   <para>
    Метка времени начала запроса
    доступна в переменной <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">Предопределённые константы даты и времени</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
-->