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

<!-- EN-Revision: 3a8c3e77df070a046c9d5b56b68926ca2d7e5ee3 Maintainer: tmn Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="function.date-parse" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>date_parse</refname>

<refpurpose>

Возвращает ассоциативный массив с подробной информацией о заданной дате/времени

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>array</type><methodname>date_parse</methodname>

<methodparam><type>string</type><parameter>datetime</parameter></methodparam>

</methodsynopsis>

<para>

Функция <function>date_parse</function> разбирает строку

параметра <parameter>datetime</parameter> аналогично

функции <function>strtotime</function> или методу <function>DateTimeImmutable::__construct</function>,

но вместо возврата метки Unix-времени, как это делает функция <function>strtotime</function>, или объекта

<classname>DateTimeImmutable</classname>, который создаёт метод <function>DateTimeImmutable::__construct</function>),

функция возвращает ассоциативный массив с информацией,

которую функция обнаружила в строке параметра <parameter>datetime</parameter>.

</para>

<para>

Функция установит элементам массива значение &false; или пропустит элемент,

если не найдёт информацию о конкретных компонентах даты и времени.

Поэтому в PHP предусмотрели другие функции для работы с датой и временем,

которые при том же значении параметра <parameter>datetime</parameter>

умеют создавать метку времени или объект <classname>DateTimeImmutable</classname>,

в котором заполняют значения для большего количества компонентов времени,

тогда как эта функция для аналогичных компонентов устанавливает значение &false;.

Примеры на этой странице показывают обработку строк, из которых невозможно извлечь отдельные компоненты времени.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Строка с датой и временем в формате, который распознаёт метод <function>DateTimeImmutable::__construct</function>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает массив (<type>array</type>) с информацией о дате и времени.

</para>

<para>

Результирующий массив содержит следующие ключи: <literal>year</literal>,

<literal>month</literal>, <literal>day</literal>, <literal>hour</literal>,

<literal>minute</literal>, <literal>second</literal>,

<literal>fraction</literal> и <literal>is_localtime</literal>.

</para>

<para>

Элемент <literal>zone_type</literal> укажет тип часового пояса, если массив с результатами содержит элемент <literal>is_localtime</literal>.

Для <literal>1</literal>-го типа представления часовых поясов — со смещением относительно UTC — добавляются поля <literal>zone</literal> и <literal>is_dst</literal>;

для <literal>2</literal>-го типа представления — аббревиатура — добавляются поля <literal>tz_abbr</literal> и <literal>is_dst</literal>;

для <literal>3</literal>-го тип — идентификатор часового пояса — добавляются поля <literal>tz_abbr</literal> и <literal>tz_id</literal>.

</para>

<para>

Функция включит в массив с результатами массив <literal>relative</literal>,

если строка <parameter>datetime</parameter> содержит элементы относительного времени

наподобие <literal>+3 days</literal>.

Массив с результатами разбора элементов времени в относительном формате содержит следующие ключи:

<literal>year</literal>, <literal>month</literal>, <literal>day</literal>,

<literal>hour</literal>, <literal>minute</literal>,

<literal>second</literal> и, если строка содержит названия дней недели или относительные количества рабочих дней,

<literal>weekday</literal> и <literal>weekdays</literal>.

</para>

<para>

Массив включает поля <literal>warning_count</literal> и <literal>warnings</literal>.

Первое указывает количество предупреждений.

Ключи элементов массива <literal>warnings</literal> указывают позицию в аргументе <parameter>datetime</parameter>,

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

</para>

<para>

Массив также содержит поля <literal>error_count</literal> и <literal>errors</literal>.

Первое указывает количество ошибок.

Ключи элементов массива <literal>errors</literal> указывают позицию в аргументе <parameter>datetime</parameter>,

на которой возникла ошибка, а строковое значение содержит описание ошибки.

</para>

<warning>

<para>

Функция запишет в массивы <literal>warnings</literal>

и <literal>errors</literal> меньшее количество элементов,

чем указывают значения элементов <literal>warning_count</literal> и <literal>error_count</literal>,

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

</para>

</warning>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

При недопустимом формате даты и времени во входной строке

функция заполнит массив 'errors' элементами с сообщениями об ошибках.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.2.0</entry>

<entry>

Элемент <literal>zone</literal> в массиве результатов теперь содержит

секунды вместо минут, а знак инвертируется, например:

значение <literal>-120</literal> теперь выводится как <literal>7200</literal>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример разбора полной строки даты и времени <parameter>datetime</parameter>а функцией <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("2006-12-12 10:00:00.5"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(12) {

["year"]=>

int(2006)

["month"]=>

int(12)

["day"]=>

int(12)

["hour"]=>

int(10)

["minute"]=>

int(0)

["second"]=>

int(0)

["fraction"]=>

float(0.5)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(false)

}

]]>

</screen>

</example>

</para>

<para>

Функция включает элементы часового пояса в результаты,

только если строка параметра <parameter>datetime</parameter> содержит информацию о часовом поясе.

Для часовых поясов функция включает элемент <literal>zone_type</literal> и ряд других элементов в зависимости от значения типа представления часового пояса.

<example>

<title>Пример разбора строки с аббревиатурой часового пояса функцией <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(16) {

["year"]=>

int(2022)

["month"]=>

int(6)

["day"]=>

int(2)

["hour"]=>

int(10)

["minute"]=>

int(28)

["second"]=>

int(17)

["fraction"]=>

float(0)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(true)

["zone_type"]=>

int(2)

["zone"]=>

int(0)

["is_dst"]=>

bool(true)

["tz_abbr"]=>

string(3) "BST"

}

]]>

</screen>

</example>

<example>

<title>Пример разбора строки с идентификатором часового пояса функцией <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(14) {

["year"]=>

int(2022)

["month"]=>

int(6)

["day"]=>

int(2)

["hour"]=>

int(10)

["minute"]=>

int(28)

["second"]=>

int(17)

["fraction"]=>

float(0)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(true)

["zone_type"]=>

int(3)

["tz_id"]=>

string(13) "Europe/London"

}

]]>

</screen>

</example>

</para>

<para>

При разборе немногословной строки <parameter>datetime</parameter> функция возвращает меньше информации.

В следующем примере функция возвращает массив, в котором все компоненты времени содержат значение &false;.

<example>

<title>Пример разбора строки с минимумом информации о дате функцией <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("June 2nd, 2022"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(12) {

["year"]=>

int(2022)

["month"]=>

int(6)

["day"]=>

int(2)

["hour"]=>

bool(false)

["minute"]=>

bool(false)

["second"]=>

bool(false)

["fraction"]=>

bool(false)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(false)

}

]]>

</screen>

</example>

</para>

<para>

<link linkend="datetime.formats.relative">Относительные форматы</link> не влияют на значения,

которые функция извлекла при разборе абсолютных форматов даты и времени, но результаты разбора относительных форматов включаются в элемент "relative".

<example>

<title>Пример разбора строки с относительными форматами даты и времени функцией <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(13) {

["year"]=>

int(2006)

["month"]=>

int(12)

["day"]=>

int(12)

["hour"]=>

int(10)

["minute"]=>

int(0)

["second"]=>

int(0)

["fraction"]=>

float(0.5)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(false)

["relative"]=>

array(6) {

["year"]=>

int(0)

["month"]=>

int(0)

["day"]=>

int(7)

["hour"]=>

int(1)

["minute"]=>

int(0)

["second"]=>

int(0)

}

}

]]>

</screen>

</example>

</para>

<para>

При разборе названий дней недели наподобие <literal>Thursday</literal> функция установит для компонентов

hour, minute, second и fraction значение <literal>0</literal>. При передаче значения <literal>Thursday</literal>

в метод <function>DateTimeImmutable::__construct</function> для каждого компонента времени также устанавливается значение <literal>0</literal>.

В следующем примере для элемента year, однако, функция оставляет значение &false;.

<example>

<title>Пример побочных эффектов в работе функции <function>date_parse</function></title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(date_parse("Thursday, June 2nd"));

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

array(13) {

["year"]=>

bool(false)

["month"]=>

int(6)

["day"]=>

int(2)

["hour"]=>

int(0)

["minute"]=>

int(0)

["second"]=>

int(0)

["fraction"]=>

float(0)

["warning_count"]=>

int(0)

["warnings"]=>

array(0) {

}

["error_count"]=>

int(0)

["errors"]=>

array(0) {

}

["is_localtime"]=>

bool(false)

["relative"]=>

array(7) {

["year"]=>

int(0)

["month"]=>

int(0)

["day"]=>

int(0)

["hour"]=>

int(0)

["minute"]=>

int(0)

["second"]=>

int(0)

["weekday"]=>

int(4)

}

}

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>date_parse_from_format</function> для разбора параметра <parameter>datetime</parameter> с определённым заданным форматом</member>

<member><function>checkdate</function> для проверки григорианской даты</member>

<member><function>getdate</function></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

-->