format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 7f7fce55c075567a9b964be1d6ff131922930b17 Maintainer: tmn Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>DateTimeInterface::format</refname>
  <refname>DateTimeImmutable::format</refname>
  <refname>DateTime::format</refname>
  <refname>date_format</refname>
  <refpurpose>Возвращает дату, которую отформатировал по заданному формату</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="DateTimeInterface">
   <modifier>public</modifier> <type>string</type><methodname>DateTimeInterface::format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
  </methodsynopsis>
  <methodsynopsis role="DateTimeImmutable">
   <modifier>public</modifier> <type>string</type><methodname>DateTimeImmutable::format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
  </methodsynopsis>
  <methodsynopsis role="DateTime">
   <modifier>public</modifier> <type>string</type><methodname>DateTime::format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type>string</type><methodname>date_format</methodname>
   <methodparam><type>DateTimeInterface</type><parameter>object</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
  </methodsynopsis>
  <para>
   Метод возвращает строку с датой в формате, который указали при вызове метода.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   &date.datetime.description;
   <varlistentry>
    <term><parameter>format</parameter></term>
    <listitem>
     <para>
      Шаблон результирующей строки (<type>string</type>) с датой. Смотрите параметры
      форматирования ниже. Вместо шаблона также указывают <link
      linkend="datetimeinterface.constants.types">предопределённые константы даты и времени</link>,
      например, константа
      <constant>DATE_RSS</constant> содержит строку формата <literal>'D, d M Y H:i:s'</literal>.
     </para>
     <para>
      <table>
       <title>
        Символы, которые метод распознаёт в строке параметра <parameter>format</parameter>
        </title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Символ в строке <parameter>format</parameter></entry>
          <entry>Описание</entry>
          <entry>Пример возвращаемого значения</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry align="center"><emphasis>День</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>d</literal></entry>
          <entry>День месяца, 2 цифры с ведущим нулём</entry>
          <entry>От <literal>01</literal> до <literal>31</literal></entry>
         </row>
         <row>
          <entry><literal>D</literal></entry>
          <entry>Текстовое представление дня недели, 3 символа</entry>
          <entry>От <literal>Mon</literal> до <literal>Sun</literal></entry>
         </row>
         <row>
          <entry><literal>j</literal></entry>
          <entry>День месяца без ведущего нуля</entry>
          <entry>От <literal>1</literal> до <literal>31</literal></entry>
         </row>
         <row>
          <entry><literal>l</literal> (строчная 'L')</entry>
          <entry>Полное наименование дня недели</entry>
          <entry>От <literal>Sunday</literal> до <literal>Saturday</literal></entry>
         </row>
         <row>
          <entry><literal>N</literal></entry>
          <entry>
           Числовое представление дня недели по стандарту ISO 8601
          </entry>
          <entry>
           От <literal>1</literal> для понедельника до <literal>7</literal> для воскресенья
          </entry>
         </row>
         <row>
          <entry><literal>S</literal></entry>
          <entry>
           Английское наращение — суффикс для порядкового числительного, которое означает день месяца, 2 буквы
          </entry>
          <entry>
           Значения <literal>st</literal>, <literal>nd</literal>, <literal>rd</literal>
           или <literal>th</literal>. Опция хорошо работает с параметром формата <literal>j</literal>
          </entry>
         </row>
         <row>
          <entry><literal>w</literal></entry>
          <entry>Порядковый номер дня недели</entry>
          <entry>От <literal>0</literal> для воскресенья до <literal>6</literal> для субботы</entry>
         </row>
         <row>
          <entry><literal>z</literal></entry>
          <entry>Порядковый номер дня в году начиная с 0</entry>
          <entry>От <literal>0</literal> до <literal>365</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Неделя</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>W</literal></entry>
          <entry>Порядковый номер недели года
           по стандарту ISO 8601; недели начинаются с понедельника</entry>
          <entry>Например: <literal>42</literal> — 42-я неделя года</entry>
         </row>
         <row>
          <entry align="center"><emphasis>Месяц</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>F</literal></entry>
          <entry>Полное название месяца, например January или March</entry>
          <entry>От <literal>January</literal> до <literal>December</literal></entry>
         </row>
         <row>
          <entry><literal>m</literal></entry>
          <entry>Порядковый номер месяца с ведущим нулём</entry>
          <entry>От <literal>01</literal> до <literal>12</literal></entry>
         </row>
         <row>
          <entry><literal>M</literal></entry>
          <entry>Сокращённое название месяца, 3 символа</entry>
          <entry>От <literal>Jan</literal> до <literal>Dec</literal></entry>
         </row>
         <row>
          <entry><literal>n</literal></entry>
          <entry>Порядковый номер месяца без ведущего нуля</entry>
          <entry>От <literal>1</literal> до <literal>12</literal></entry>
         </row>
         <row>
          <entry><literal>t</literal></entry>
          <entry>Количество дней в заданном месяце</entry>
          <entry>От <literal>28</literal> до <literal>31</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Год</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>L</literal></entry>
          <entry>Признак високосного года</entry>
          <entry>
           <literal>1</literal>, если год високосный, иначе <literal>0</literal>
          </entry>
         </row>
         <row>
          <entry><literal>o</literal></entry>
          <entry>
           Номер года с учётом нумерации недель стандартом ISO 8601. Параметр возвращает то же значение,
           что и параметр <literal>Y</literal>, за исключением случаев, когда номер недели по стандарту ISO,
           как возвращает параметр <literal>W</literal>, принадлежит предыдущему или следующему году, тогда
           возвращается год, которому принадлежит такая неделя
          </entry>
          <entry>Примеры: <literal>1999</literal> или <literal>2003</literal></entry>
         </row>
         <row>
          <entry><literal>X</literal></entry>
          <entry>
           Расширенное полное числовое представление года, не менее 4 цифр,
           с знаком <literal>-</literal> перед значением года, если год относится к периоду до нашей эры,
           и знаком <literal>+</literal> перед значением года, если год относится к нашей эре
          </entry>
          <entry>
           Примеры: <literal>-0055</literal>, <literal>+0787</literal>,
           <literal>+1999</literal>, <literal>+10191</literal>
          </entry>
         </row>
         <row>
          <entry><literal>x</literal></entry>
          <entry>
           Расширенное полное числовое представление, если требуется,
           или стандартное полное числовое представление по аналогии с параметром <literal>Y</literal>,
           если возможно. Не менее четырёх цифр.
           Параметр добавит знак <literal>-</literal> перед значением года, если год относится к периоду до нашей эры.
           Перед значениями года после (и включая) <literal>10000</literal> параметр добавит знак <literal>+</literal>
          </entry>
          <entry>
           Примеры: <literal>-0055</literal>, <literal>0787</literal>,
           <literal>1999</literal>, <literal>+10191</literal>
          </entry>
         </row>
         <row>
          <entry><literal>Y</literal></entry>
          <entry>
           Полное числовое представление года, не менее 4 цифр, со знаком <literal>-</literal>
           перед значениями лет до нашей эры
          </entry>
          <entry>
           Примеры: <literal>-0055</literal>, <literal>0787</literal>,
           <literal>1999</literal>, <literal>2003</literal>,
           <literal>10191</literal>
          </entry>
         </row>
         <row>
          <entry><literal>y</literal></entry>
          <entry>Номер года, 2 цифры</entry>
          <entry>Примеры: <literal>99</literal>, <literal>03</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Время</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>a</literal></entry>
          <entry>
           Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в нижнем регистре
          </entry>
          <entry><literal>am</literal> или <literal>pm</literal></entry>
         </row>
         <row>
          <entry><literal>A</literal></entry>
          <entry>
           Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в верхнем регистре
          </entry>
          <entry><literal>AM</literal> или <literal>PM</literal></entry>
         </row>
         <row>
          <entry><literal>B</literal></entry>
          <entry>
           Время в формате интернет-времени — альтернативной системы отсчета времени суток,
           которую предложила швейцарская компания — производитель часов Swatch
          </entry>
          <entry>От <literal>000</literal> до <literal>999</literal></entry>
         </row>
         <row>
          <entry><literal>g</literal></entry>
          <entry>Часы в 12-часовом формате без ведущего нуля</entry>
          <entry>От <literal>1</literal> до <literal>12</literal></entry>
         </row>
         <row>
          <entry><literal>G</literal></entry>
          <entry>Часы в 24-часовом формате без ведущего нуля</entry>
          <entry>От <literal>0</literal> до <literal>23</literal></entry>
         </row>
         <row>
          <entry><literal>h</literal></entry>
          <entry>Часы в 12-часовом формате с ведущим нулём</entry>
          <entry>От <literal>01</literal> до <literal>12</literal></entry>
         </row>
         <row>
          <entry><literal>H</literal></entry>
          <entry>Часы в 24-часовом формате с ведущим нулём</entry>
          <entry>От <literal>00</literal> до <literal>23</literal></entry>
         </row>
         <row>
          <entry><literal>i</literal></entry>
          <entry>Минуты с ведущим нулём</entry>
          <entry>От <literal>00</literal> до <literal>59</literal></entry>
         </row>
         <row>
          <entry><literal>s</literal></entry>
          <entry>Секунды с ведущим нулём</entry>
          <entry>От <literal>00</literal> до <literal>59</literal></entry>
         </row>
         <row>
          <entry><literal>u</literal></entry>
          <entry>
           Микросекунды. Обратите внимание, что функция <function>date</function>
           генерирует для поля микросекунд значение <literal>000000</literal>,
           поскольку принимает метку времени как целочисленное (<type>int</type>) значение в секундах,
           тогда как метод <methodname>DateTimeInterface::format</methodname> поддерживает микросекунды,
           если объект <interfacename>DateTimeInterface</interfacename> создали с микросекундами
          </entry>
          <entry>Например: <literal>654321</literal></entry>
         </row>
         <row>
          <entry><literal>v</literal></entry>
          <entry>
           Миллисекунды. Примечание к параметру <literal>u</literal> касается
           и этого параметра
          </entry>
          <entry>Пример: <literal>654</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Часовой пояс</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>e</literal></entry>
          <entry>Идентификатор часового пояса</entry>
          <entry>
           Примеры: <literal>UTC</literal>, <literal>GMT</literal>, <literal>Atlantic/Azores</literal>
          </entry>
         </row>
         <row>
          <entry><literal>I</literal> (заглавная i)</entry>
          <entry>Признак летнего времени</entry>
          <entry>
           <literal>1</literal>, если дата соответствует летнему времени, иначе <literal>0</literal>
          </entry>
         </row>
         <row>
          <entry><literal>O</literal></entry>
          <entry>Разница со временем по Гринвичу без двоеточия между часами и минутами</entry>
          <entry>Например: <literal>+0200</literal></entry>
         </row>
         <row>
          <entry><literal>P</literal></entry>
          <entry>Разница со временем по Гринвичу с двоеточием между часами и минутами</entry>
          <entry>Например: <literal>+02:00</literal></entry>
         </row>
         <row>
          <entry><literal>p</literal></entry>
          <entry>
           То же, что и параметр <literal>P</literal>, но вместо <literal>+00:00</literal> возвращает <literal>Z</literal>.
           Параметр доступен с PHP 8.0.0
          </entry>
          <entry>Например: <literal>Z</literal> или <literal>+02:00</literal></entry>
         </row>
         <row>
          <entry><literal>T</literal></entry>
          <entry>Аббревиатура часового пояса, если известна; иначе смещение по Гринвичу</entry>
          <entry>Примеры: <literal>EST</literal>, <literal>MDT</literal>, <literal>+05</literal></entry>
         </row>
         <row>
          <entry><literal>Z</literal></entry>
          <entry>
           Смещение часового пояса в секундах. Смещение для часовых поясов
           к западу от времени UTC — отрицательное, а для часовых поясов к востоку
           от времени UTC — положительное
          </entry>
          <entry>От <literal>-43200</literal> до <literal>50400</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Полная дата/время</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>c</literal></entry>
          <entry>Дата в формате стандарта ISO 8601</entry>
          <entry>2004-02-12T15:19:21+00:00</entry>
         </row>
         <row>
          <entry><literal>r</literal></entry>
          <entry>
           Дата в формате стандартов <link xlink:href="&url.rfc;2822">RFC 222</link>
           и <link xlink:href="&url.rfc;5322">RFC 5322</link>
          </entry>
          <entry>Например: <literal>Thu, 21 Dec 2000 16:01:07 +0200</literal></entry>
         </row>
         <row>
          <entry><literal>U</literal></entry>
          <entry>
           Количество секунд, которые прошли с начала Unix-эпохи — с 1 января 1970 00:00:00 GMT
          </entry>
          <entry>Смотрите также <function>time</function></entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
     <para>
      Метод выводит нераспознанные в строке формата символы без изменений.
      Параметр <literal>Z</literal> возвращает <literal>0</literal>
      при каждом вызове функции <function>gmdate</function>.
     </para>
     <note>
      <para>
       Поскольку эта функция принимает
       только целочисленные (<type>int</type>) метки времени,
       форматирующий символ <literal>u</literal> будет полезен
       только при работе с функцией <function>date_format</function> и пользовательскими
       метками времени, которые создали функцией <function>date_create</function>.
      </para>
     </note>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   В случае успешного выполнения метод возвращает строку с отформатированной датой.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Добавили символы форматирования <literal>X</literal> и <literal>x</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Добавили символ форматирования <literal>p</literal>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
 &reftitle.examples;
  <para>
  <example>
   <title>Пример использования метода <function>DateTimeInterface::format</function></title>
   <para>&style.oop;</para>
   <programlisting role="php">
    <![CDATA[
<?php

$date = new DateTimeImmutable('2000-01-01');
echo $date->format('Y-m-d H:i:s');

?>
]]>
   </programlisting>
   <para>&style.procedural;</para>
   <programlisting role="php">
<![CDATA[
<?php

$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
2000-01-01 00:00:00
]]>
   </screen>
  </example>
 </para>
  <para>
   <example>
    <title>Больше примеров</title>
    <programlisting role="php">
<![CDATA[
<?php

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

// Время «сейчас»
$date = new DateTimeImmutable();

// Выведет что-то наподобие: Wednesday
echo $date->format('l'), "\n";

// Выведет что-то наподобие: Wednesday 19th of October 2022 08:40:48 AM
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

/* Передача констант в параметр format */
// Выведет что-то наподобие: Wed, 19 Oct 2022 08:40:48 +0000
echo $date->format(DateTimeInterface::RFC2822), "\n";

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Разворачивание символа в строке формата, который распознал метод, останавливают путём
   экранирования символа форматирования обратным слешем.
   Иногда требуется заэкранировать сам обратный слеш, если символ с обратным слешем
   образует управляющую последовательность.
   <example>
    <title>Пример экранирования символов при форматировании</title>
    <programlisting role="php">
<![CDATA[
<?php

$date = new DateTimeImmutable();

// Выведет что-то наподобие: Wednesday the 19th
echo $date->format('l \t\h\e jS');

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Чтобы отформатировать даты на других языках, вместо метода <methodname>DateTimeInterface::format</methodname>
   вызывают метод <methodname>IntlDateFormatter::format</methodname>.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <para>
   Метод не учитывает настройки локали и выводит данные на английском языке.
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>date</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
-->