mirror of
https://github.com/php/doc-ru.git
synced 2026-03-24 07:42:22 +01:00
898 lines
42 KiB
XML
898 lines
42 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- EN-Revision: f5e51d56b0a4dd7e70dd47ea7eb3c07fdc207ddd Maintainer: shein Status: ready -->
|
||
<!-- Reviewed: no -->
|
||
<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">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
|
||
echo $date->format('Y-m-d');
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Пример передачи в метод <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>
|
||
<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">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
echo 'Текущее время: ' . date('Y-m-d H:i:s') . "\n";
|
||
|
||
// Поля «год», «месяц» и «день» метод распознает в строке разбора,
|
||
// а поля «час», «минута» и «секунда» заполнит значениями системного времени
|
||
$format = 'Y-m-d';
|
||
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
|
||
echo "Формат: $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 "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";
|
||
|
||
/**
|
||
* Метод распознает каждое поле в строке разбора,
|
||
* а затем сбросит поля «год» и «месяц» на начальные значения даты и времени Unix-эпохи,
|
||
* поскольку эти параметры оказались слева от символа «!» в строке формата,
|
||
* а поля «день», «час», «минута» и «секунда» сохранят значения, которые получили из строки разбора,
|
||
* поскольку эти параметры оказались справа от символа «!» и метод распознал для них значения;
|
||
* дробная часть времени со значением долей секунды вернёт значение 000000, поскольку метод
|
||
* не разобрал ни милли-, ни микросекунды, а другие поля времени при этом указали
|
||
*/
|
||
$format = 'Y-m-!d H:i:s';
|
||
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
|
||
echo "Формат: $format; " . $date->format('Y-m-d H:i:s.u') . "\n";
|
||
|
||
/**
|
||
* Метод заполнит поле «день» значением «15», поскольку в строке формата указали символ дня
|
||
* и метод распознал в строке разбора значение для этого параметра,
|
||
* а остальные поля даты и времени метод сбросит на начальные значения
|
||
* даты и времени эпохи Unix, поскольку для этих полей не указали
|
||
* параметры и значения в строках формата и разбора
|
||
*/
|
||
$format = '!d';
|
||
$date = DateTimeImmutable::createFromFormat($format, '15');
|
||
echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";
|
||
|
||
/**
|
||
* Метод заполнит поле «минуты» значением 15,
|
||
* поскольку распознал в строке разбора значение для символа минут i.
|
||
* Поля «год», «месяц» и «день» получат значения системной даты,
|
||
* поскольку метод не разобрал эти поля в строках формата и разбора, а в строке формата
|
||
* не было символов «!» или «|», при которых год, месяц и день получили бы значения начала Unix-эпохи.
|
||
* А остальным полям времени метод установит нулевые значения,
|
||
* поскольку метод не нашёл эти параметры и значения для них в строках формата и разбора,
|
||
* но методу удалось разобрать хотя бы одно временно́е поле
|
||
*/
|
||
$format = 'i';
|
||
$date = DateTimeImmutable::createFromFormat($format, '15');
|
||
echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs.similar;
|
||
<screen>
|
||
<![CDATA[
|
||
Текущее время: 2022-06-02 15:50:46
|
||
Формат: Y-m-d; 2009-02-15 15:50:46
|
||
Формат: Y-m-d H:i:s; 2009-02-15 15:16:17
|
||
Формат: Y-m-!d H:i:s; 1970-01-15 15:16:17
|
||
Формат: !d; 1970-01-15 00:00:00
|
||
Формат: i; 2022-06-02 00:15:00
|
||
]]>
|
||
</screen>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Пример строки формата с литеральными символами</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>Пример поведения при переполнении</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>
|
||
Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:
|
||
</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">
|
||
<![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>
|
||
Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:
|
||
</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">
|
||
<![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>Пример жадного поведения при разборе</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>
|
||
Символ формата <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>
|
||
<!-- 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
|
||
-->
|