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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 50dcf55ce543220dd8375df2fdb4f7db702b9c9f 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; или будут отсутствовать.
   Если это необходимо для построения временной метки или объекта <classname>DateTimeImmutable</classname>
   из одной и той же строки параметра <parameter>datetime</parameter>,
   большее количество полей может быть установлено в значение не &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>is_localtime</literal>, то <literal>zone_type</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>
   Если в параметре <parameter>datetime</parameter> присутствуют элементы относительного времени,
   например, <literal>+3 days</literal>, то возвращаемый массив включает вложенный массив с ключом <literal>relative</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>Пример использования функции <function>date_parse</function> с полной строкой <parameter>datetime</parameter></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>, установят временную часть строки в значение <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
-->