<?xml version="1.0" encoding="utf-8"?>

<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>Разбирает строку времени по заданному формату</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>

Метод возвращает новый объект DateTimeImmutable,

который представляет строку даты и времени <parameter>datetime</parameter>

в формате <parameter>format</parameter>.

</para>

</refsect1>

<refsect1 role="parameters" xml:id="datetimeimmutable.createfromformat.parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>format</parameter></term>

<listitem>

<para>

Формат даты и времени в виде строки (<type>string</type>), которому

соответствует значение второго аргумента функции. Список параметров

форматирования приводят следующие параграфы. В большей части случаев

работают те же символы, что и для функции <function>date</function>.

</para>

<para>

Метод инициализирует каждое поле текущей датой и временем системы. Поля часто приходится «обнулять»

до значений начала эпохи Unix — <literal>1970-01-01 00:00:00 UTC</literal>.

Поля, которые не указали в строке формата <parameter>format</parameter>,

сбрасывают до начальных значений Unix-эпохи путём включения в начало строки формата

символа <literal>!</literal> или в конец строки формата символа <literal>|</literal>.

Подробнее о работе символов рассказывает документация к каждому параметру в таблице ниже.

</para>

<para>

Метод анализирует формат слева направо, поэтому в отдельных случаях порядок

расположения символов формата влияет на результат. Методу вначале требуется

проанализировать год, например, через символы <literal>Y</literal> или <literal>y</literal>,

если строка формата содержит символ <literal>z</literal>, для которого метод ищет день года.

</para>

<para>

Символы для разбора чисел допускают широкий диапазон значений,

который выходит за пределы логического диапазона. Например,

символ <literal>d</literal>, для которого метод ищет в строке разбора день месяца,

принимает значения в диапазоне от <literal>00</literal> до <literal>99</literal>.

Единственное ограничение — количество цифр.

Когда задают значения, которые выходят за пределы диапазона,

срабатывает механизм переполнения анализатора даты и времени.

Примеры ниже показывают отдельные проявления такого поведения.

</para>

<para>

Это также означает, что данные, которые метод анализирует для буквы формата, — жадные,

и будут считываться до того количества цифр, которое допускает формат.

Иногда это также означает, что в строке <parameter>datetime</parameter> уже не хватает

символов для следующих символов формата. Пример на этой странице также иллюстрирует эту проблему.

</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> и <literal>j</literal></entry>

<entry>

День месяца, 2 цифры с ведущим нулём или без него

</entry>

<entry>

От <literal>01</literal> до <literal>31</literal>

или от <literal>1</literal> до <literal>31</literal>.

Параметр принимает двузначные числа, которые превышают количество дней в месяце,

тогда месяц переполняется и разница переносится на следующий месяц.

Например, число 33 с январём означает 2 февраля

</entry>

</row>

<row>

<entry><literal>D</literal> и <literal>l</literal></entry>

<entry>

Текстовое представление дня недели

</entry>

<entry>

От <literal>Mon</literal> до <literal>Sun</literal>

или от <literal>Sunday</literal> до <literal>Saturday</literal>.

Дата переполняется до <emphasis>следующей</emphasis> даты с заданным названием дня недели,

если заданное название дня недели отличается от названия дня,

который принадлежит разобранной дате (или дате по умолчанию).

Примеры ниже содержат объяснение

</entry>

</row>

<row>

<entry><literal>S</literal></entry>

<entry>

Английское наращение — суффикс для порядкового числительного, которое означает день месяца, 2 буквы.

Метод пропустит эти буквы при разборе строки

</entry>

<entry>

<literal>st</literal>, <literal>nd</literal>, <literal>rd</literal>

или <literal>th</literal>

</entry>

</row>

<row>

<entry><literal>z</literal></entry>

<entry>

День года начиная с 0;

перед параметром требуется указать параметр <literal>Y</literal> или <literal>y</literal>

</entry>

<entry>

От <literal>0</literal> до <literal>365</literal>.

Параметр принимает трёхзначные числа, которые превышают количество дней в году,

тогда год переполняется и разница переносится на следующий год.

Например, число 366 с 2022 годом означает 2 января 2023 года

</entry>

</row>

<row>

<entry align="center"><emphasis>Месяц</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>F</literal> и <literal>M</literal></entry>

<entry>

Текстовое представление названия месяца, например January или Sept

</entry>

<entry>

С <literal>January</literal> по <literal>December</literal>

или с <literal>Jan</literal> по <literal>Dec</literal>

</entry>

</row>

<row>

<entry><literal>m</literal> и <literal>n</literal></entry>

<entry>

Числовое представление номера месяца в году с ведущим нулём или без него

</entry>

<entry>

От <literal>01</literal> до <literal>12</literal>

или от <literal>1</literal> до <literal>12</literal>.

Параметр принимает двузначные числа больше 12, тогда год переполняется

и разница переносится на следующий год.

Например, число 13 означает январь следующего года

</entry>

</row>

<row>

<entry align="center"><emphasis>Год</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>X</literal> и <literal>x</literal></entry>

<entry>

Полное числовое представление года длиной <emphasis>до</emphasis> 19 цифр

с необязательным префиксом <literal>+</literal> или <literal>-</literal>

</entry>

<entry>

Примеры: <literal>0055</literal>, <literal>787</literal>,

<literal>1999</literal>, <literal>-2003</literal>,

<literal>+10191</literal>

</entry>

</row>

<row>

<entry><literal>Y</literal></entry>

<entry>

Полное числовое представление года длиной <emphasis>до</emphasis> 4 цифр

</entry>

<entry>

Примеры: <literal>25</literal> (аналогично <literal>0025</literal>),

<literal>787</literal>, <literal>1999</literal>, <literal>2003</literal>

</entry>

</row>

<row>

<entry><literal>y</literal></entry>

<entry>

Двузначное представление года в диапазоне 1970-2069 включительно

</entry>

<entry>

Примеры:

<literal>99</literal> или <literal>03</literal>,

которые метод интерпретирует как <literal>1999</literal>

и <literal>2003</literal>

</entry>

</row>

<row>

<entry align="center"><emphasis>Время</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>a</literal> и <literal>A</literal></entry>

<entry>

Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня»)

</entry>

<entry>

Регистронезависимые обозначения <literal>am</literal> или <literal>pm</literal>

</entry>

</row>

<row>

<entry><literal>g</literal> и <literal>h</literal></entry>

<entry>

12-часовой формат часа с ведущим нулём или без него

</entry>

<entry>

От <literal>1</literal> до <literal>12</literal>

или от <literal>01</literal> до <literal>12</literal>.

Параметр принимает двузначные числа больше 12, тогда день переполняется

и разница переносится на следующий день.

Например, число <literal>14</literal> означает <literal>02</literal> часа

следующего AM- или PM-периода

</entry>

</row>

<row>

<entry><literal>G</literal> и <literal>H</literal></entry>

<entry>

24-часовой формат часа с ведущим нулём или без него

</entry>

<entry>

От <literal>0</literal> до <literal>23</literal>

или от <literal>00</literal> до <literal>23</literal>.

Параметр принимает двузначные числа больше 24, тогда день переполняется

и разница переносится на следующий день.

Например, число <literal>26</literal> означает <literal>02:00</literal> следующего дня

</entry>

</row>

<row>

<entry><literal>i</literal></entry>

<entry>

Минуты с ведущим нулём

</entry>

<entry>

От <literal>00</literal> до <literal>59</literal>.

Параметр принимает двузначные числа больше 59, тогда час переполняется

и разница переносится на следующий час.

Например, число <literal>66</literal> означает <literal>:06</literal> минут следующего часа

</entry>

</row>

<row>

<entry><literal>s</literal></entry>

<entry>Секунды с ведущим нулём</entry>

<entry>

От <literal>00</literal> до <literal>59</literal>.

Параметр принимает двузначные числа больше 59, тогда час переполняется

и разница переносится на следующую минуту.

Например, число <literal>90</literal> означает <literal>:30</literal> секунд следующей минуты

</entry>

</row>

<row>

<entry><literal>v</literal></entry>

<entry>Миллисекунды длиной до 3 цифр</entry>

<entry>

Примеры: <literal>12</literal> (<literal>0.12</literal> секунды),

<literal>345</literal> (<literal>0.345</literal> секунды)

</entry>

</row>

<row>

<entry><literal>u</literal></entry>

<entry>Микросекунды длиной до 6 цифр</entry>

<entry>

Примеры: <literal>45</literal> (<literal>0.45</literal> секунды),

<literal>654321</literal> (<literal>0.654321</literal> секунды)

</entry>

</row>

<row>

<entry align="center"><emphasis>Часовой пояс</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry>

<literal>e</literal>, <literal>O</literal>, <literal>p</literal>,

<literal>P</literal> и <literal>T</literal>

</entry>

<entry>

Идентификатор часового пояса, разница в часах относительно

UTC, разница относительно UTC с двоеточием между часами и минутами

или аббревиатура часового пояса

</entry>

<entry>

Примеры: <literal>UTC</literal>; <literal>GMT</literal>;

<literal>Atlantic/Azores</literal>, <literal>+0200</literal>,

<literal>+02:00</literal> или <literal>EST</literal>; <literal>MDT</literal>

</entry>

</row>

<row>

<entry align="center"><emphasis>Полные дата и время</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>U</literal></entry>

<entry>

Количество секунд с начала эпохи Unix — January 1 1970 00:00:00 GMT

</entry>

<entry>Пример: <literal>1292177455</literal></entry>

</row>

<row>

<entry align="center"><emphasis>Пробел и разделители</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal> </literal> (пробел)</entry>

<entry>

Ноль или более символов пробела, табуляции, неразрывного пробела NBSP (U+A0)

или узкого неразрывного пробела NNBSP (U+202F)

</entry>

<entry>Пример: <literal>"\t"</literal>, <literal>" "</literal></entry>

</row>

<row>

<entry><literal>#</literal></entry>

<entry>

Один из следующих символов разделения: <literal>;</literal>,

<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,

<literal>,</literal>, <literal>-</literal>, <literal>(</literal>

или <literal>)</literal>

</entry>

<entry>Пример: <literal>/</literal></entry>

</row>

<row>

<entry>

<literal>;</literal>,

<literal>:</literal>, <literal>/</literal>, <literal>.</literal>,

<literal>,</literal>, <literal>-</literal>, <literal>(</literal>

или <literal>)</literal>

</entry>

<entry>Заданный символ</entry>

<entry>Пример: <literal>-</literal></entry>

</row>

<row>

<entry><literal>?</literal></entry>

<entry>Случайный байт</entry>

<entry>

Пример: <literal>^</literal>. Предостережение: для символов в кодировке UTF-8

иногда требуется указать больше одного символа <literal>?</literal>,

поскольку в Юникоде отдельные символы кодируются больше чем одним байтом.

Разобрать многобайтовые символы помогает модификатор <literal>*</literal>

</entry>

</row>

<row>

<entry><literal>*</literal></entry>

<entry>

Случайные байты до следующего разделителя или цифры

</entry>

<entry>

Пример: символ <literal>*</literal> в строке формата <literal>Y-*-d</literal>

для строки разбора <literal>2009-aWord-08</literal> будет соответствовать

части <literal>aWord</literal>

</entry>

</row>

<row>

<entry><literal>!</literal></entry>

<entry>

Сбрасывает поля «год», «месяц», «день», «час», «минута»,

«секунда», «милли-» или «микросекунда» и «часовой пояс»

до начальных значений Unix-эпохи: <literal>0</literal> для часа, минуты и секунды,

<literal>1</literal> для месяца и дня, <literal>1970</literal> для года

и часового пояса по умолчанию

</entry>

<entry>

Без символа <literal>!</literal> метод установит полям

текущие дату и время системы

</entry>

</row>

<row>

<entry><literal>|</literal></entry>

<entry>

Сбрасывает значения полей «год», «месяц», «день», «час», «минута»,

«секунда», «милли-» или «микросекунда» и «часовой пояс», которые метод ещё не разобрал,

до начальных значений Unix-эпохи

</entry>

<entry>

Формат <literal>Y-m-d|</literal> установит год, месяц и день на основе информации,

которую нашёл в строке для разбора, а для часа, минуты и секунды установит значение 0

</entry>

</row>

<row>

<entry><literal>+</literal></entry>

<entry>

С этим спецификатором формата лишние данные в конце строки разбора,

добавят в структуру, которую создаёт метод, не ошибку, а предупреждение

</entry>

<entry>

Содержала ли строка разбора в конце лишние данные,

покажет метод <methodname>DateTime::getLastErrors</methodname>

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<para>

Символы в строке формата, которые метод не распознал, вызовут сбой разбора,

и метод добавит в структуру с предупреждениями и ошибками, которую он создаёт,

сообщение об ошибке. Сообщения об ошибке запрашивают методом

<methodname>DateTime::getLastErrors</methodname>.

</para>

<para>

При включении в строку формата <parameter>format</parameter> буквальных символов,

символы экранируют обратным слешем: <literal>\</literal>.

</para>

<para>

Метод сгенерирует дату и время на основе информации в строке разбора,

а частям даты и времени, которые не указали в строке формата <parameter>format</parameter>,

установит текущее время системы, если строка формата <parameter>format</parameter>

не содержит символ <literal>!</literal>.

</para>

<para>

Метод сгенерирует дату и время на основе информации в строке разбора,

а частям даты и времени, которые не указали в строке формата <parameter>format</parameter>,

и значениям слева от символа <literal>!</literal> установит значения даты и времени начала Unix-эпохи,

если строка формата <parameter>format</parameter> содержит символ <literal>!</literal>.

</para>

<para>

Метод установит нулевые значения остальным полям времени,

которые не указали в строке формата, если разобрал хотя бы один символ для поля времени.

</para>

<para>

Начало эпохи Unix — 1970-01-01 00:00:00 UTC.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>datetime</parameter></term>

<listitem>

<para>

Строка, которая представляет время.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>timezone</parameter></term>

<listitem>

<para>

Объект класса <classname>DateTimeZone</classname>, который представляет

часовой пояс.

</para>

<para>

Метод установит текущий часовой пояс, если часовой пояс

<parameter>timezone</parameter> опустили или установили для параметра значение &null;,

а дата и время <parameter>datetime</parameter> не содержит часового пояса.

</para>

<note>

<para>

Метод проигнорирует параметр <parameter>timezone</parameter>

и текущий часовой пояс, если параметр <parameter>datetime</parameter>

либо содержит метку времени UNIX наподобие <literal>946684800</literal>,

либо указывает часовой пояс наподобие <literal>2010-01-28T15:00:00+02:00</literal>.

</para>

</note>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Метод возвращает новый экземпляр класса DateTimeImmutable&return.falseforfailure;.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

Метод выбрасывает исключение <exceptionname>ValueError</exceptionname>,

если параметр <parameter>datetime</parameter> содержит NUL-байты.

</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>

Спецификатор <literal> </literal> (пробел) теперь также поддерживает символы

неразрывного пробела NBSP

(U+A0) и узкого неразрывного пробела NNBSP (U+202F).

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

Добавили спецификаторы <literal>X</literal> и <literal>x</literal>

для параметра <parameter>format</parameter>.

</entry>

</row>

<row>

<entry>8.0.21, 8.1.8, 8.2.0</entry>

<entry>

Теперь метод выбрасывает исключение <exceptionname>ValueError</exceptionname>,

если в параметр <parameter>datetime</parameter> передали NULL-байты,

что раньше метод без предупреждения игнорировал.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Добавили спецификатор <literal>v</literal> для параметра <parameter>format</parameter>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title>Пример использования метода <function>DateTimeImmutable::createFromFormat</function></title>

<para>&style.oop;</para>

<programlisting role="php">

</programlisting>

</example>

<example>

<title>Пример передачи в метод <function>DateTimeImmutable::createFromFormat</function> предопределённых констант формата</title>

<para>&style.oop;</para>

<programlisting role="php">

</programlisting>

<para>

<link linkend="datetimeinterface.constants.types">Константы форматирования</link>

в этом примере состоят из строки символов

для <link linkend="datetime.format">форматирования</link> объекта <classname>DateTimeImmutable</classname>.

В большей части случаев эти буквы совпадают с теми же элементами информации о дате и времени,

которые определили в <link linkend="datetimeimmutable.createfromformat.parameters">параметрах</link> выше,

но обычно они более мягкие.

</para>

</example>

<example>

<title>Тонкости работы метода <function>DateTimeImmutable::createFromFormat</function></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Пример строки формата с литеральными символами</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Пример поведения при переполнении</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:

</para>

<orderedlist>

<listitem>

<simpara>

<literal>97</literal> секунд переполняют <literal>1</literal> минуту

и оставляют <literal>37</literal> секунд.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>61</literal> минута переполняет <literal>1</literal> час

и оставляет <literal>1</literal> минуту.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>35</literal> дней переполняют <literal>1</literal> месяц

и оставляют <literal>4</literal> дня. Количество дней, которое останется,

зависит от месяца, поскольку не в каждом месяце одинаковое количество дней.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>18</literal> месяцев переполняют <literal>1</literal> год

и оставляют <literal>6</literal> месяцев.

</simpara>

</listitem>

</orderedlist>

</example>

<example>

<title>Пример поведения при переполнении названия дня недели</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:

</para>

<orderedlist>

<listitem>

<simpara>

Из-за переполнения дня количеством часов дата <literal>3 Aug 2020 25:00:00</literal>, понедельник,

перетекает на <literal>(Tue) 4 Aug 2020 01:00</literal>, вторник.

</simpara>

</listitem>

<listitem>

<simpara>

Метод применяет понедельник — <literal>Mon</literal>,

что переносит дату на следующий период с аналогичным названием дня недели —

<literal>Mon, 10 Aug 2020 01:00:00</literal>.

Объяснение относительных ключевых слов наподобие <literal>Mon</literal>

описывает раздел <link linkend="datetime.formats.relative">об относительных форматах</link>.

</simpara>

</listitem>

</orderedlist>

</example>

<para>

Метод <methodname>DateTimeImmutable::getLastErrors</methodname>

помогает обнаружить переполнение дат

и включает предупреждение, если возникло переполнение.

</para>

<example>

<title>Пример обнаружения переполнения дат</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Пример жадного поведения при разборе</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Символ формата <literal>G</literal> разбирает поле «час» в 24-часовом формате

с ведущим нулём или без него. Для разбора поля «час» методу требуется

разобрать 1 или 2 цифры. Поскольку строка формата первым содержит параметр G,

и строка разбора в начале содержит две цифры,

которые идут одна за другой, метод жадно считывает значение часа как <literal>60</literal>.

</para>

<para>

Каждому из следующих символов формата <literal>i</literal> и <literal>s</literal> требуется две цифры.

Поэтому число <literal>10</literal> передаётся как значение параметра <literal>i</literal>,

который ищет в строке разбора двузначное число для установки значения полю «минута»,

а для разбора параметра <literal>s</literal>,

который также ищет двузначное число для установки значения полю «секунда», не остаётся цифр.

</para>

<para>

На эту проблему в структуре, которую создаёт метод, указывает массив <literal>errors</literal>.

</para>

<para>

Кроме того, значение <literal>60</literal> для поля «час» лежит за пределами

диапазона <literal>0</literal>-<literal>24</literal>, что добавляет

в массив <literal>warnings</literal> предупреждение о недействительности времени.

</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>