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

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

<!-- Reviewed: yes -->

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

<refnamediv>

<refname>date_parse</refname>

<refpurpose>Retourne un tableau associatif avec des informations détaillées sur une date/moment donnée</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> analyse la chaîne

<parameter>datetime</parameter> donnée selon les mêmes règles que

<function>strtotime</function> et

<function>DateTimeImmutable::__construct</function>. Au lieu de

renvoyer un horodatage Unix (avec <function>strtotime</function>) ou

un objet <classname>DateTimeImmutable</classname> (avec

<function>DateTimeImmutable::__construct</function>), il renvoie un

tableau associatif avec les informations qu'il pourrait détecter dans

la chaîne <parameter>datetime</parameter> donnée.

</para>

<para>

Si aucune information sur un certain groupe d'éléments ne peut être trouvée, ces

éléments du tableau seront définis sur &false; ou seront manquants. Si nécessaire

pour construire un horodatage ou un objet <classname>DateTimeImmutable</classname>

à partir de la même chaîne <parameter>datetime</parameter>, plusieurs champs

peuvent être définis sur une valeur non-&false;. Voir les exemples ci-dessous

pour les cas où cela se produit.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Date/moment dans un format accepté par

<function>DateTimeImmutable::__construct</function>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Retourne un &array; contenant des informations sur la date/moment analysée.

</para>

<para>

Le tableau retourné a des clés pour <literal>year</literal>,

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

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

<literal>fraction</literal>, et <literal>is_localtime</literal>.

</para>

<para>

Si <literal>is_localtime</literal> est présent, alors

<literal>zone_type</literal> indique le type de fuseau horaire.

Pour le type <literal>1</literal> (décalage UTC) les champs

<literal>zone</literal> et <literal>is_dst</literal> sont ajoutés.

Pour le type <literal>2</literal> (abréviation) les champs

<literal>tz_abbr</literal> et <literal>is_dst</literal> sont ajoutés.

Pour le type <literal>3</literal> (identifiant de fuseau horaire)

les champs <literal>tz_abbr</literal> et <literal>tz_id</literal>

sont ajoutés.

</para>

<para>

Le tableau inclut les champs <literal>warning_count</literal> et

<literal>warnings</literal>. Le premier indique le nombre

d'avertissements. Les clés du tableau <literal>warnings</literal>

indiquent la position dans le paramètre <parameter>datetime</parameter>

où l'avertissement s'est produit, avec la valeur de chaîne décrivant

l'avertissement lui-même. Un exemple ci-dessous montre un tel

avertissement.

</para>

<para>

Le tableau inclut aussi les champs <literal>error_count</literal> et

<literal>errors</literal>. Le premier indique le nombre

d'erreurs. Les clés du tableau <literal>errors</literal> indiquent

la position dans le paramètre <parameter>datetime</parameter> où l'erreur

s'est produite, avec la valeur de chaîne décrivant l'avertissement

lui-même. Un exemple ci-dessous montre un tel avertissement.

</para>

<warning>

<para>

Le nombre d'éléments de tableau dans les tableaux <literal>warnings</literal> et

<literal>errors</literal> peut être inférieur à <literal>warning_count</literal>

ou <literal>error_count</literal> s'ils se sont produits à la même position.

</para>

</warning>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

Dans le cas où la fonction retourne une erreur, l'élément <literal>"errors"</literal>

contiendra les messages d'erreur.

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

L'élément <literal>zone</literal> du tableau retourné représente maintenant

des secondes au lieu des minutes, et son signe est inversé. Par exemple,

<literal>-120</literal> est maintenant <literal>7200</literal>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>date_parse</function> avec une chaîne

<parameter>datetime</parameter> complète</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>

Les éléments de fuseau horaire n'apparaissent que s'ils sont inclus

dans la chaîne <parameter>datetime</parameter> donnée. Dans ce cas,

il y aura toujours un élément <literal>zone_type</literal> et

quelques autres en fonction de sa valeur.

<example>

<title><function>date_parse</function> avec des informations abrégées sur le fuseau horaire</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> avec des informations abrégées sur le fuseau horaire</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>

Si une chaîne <parameter>datetime</parameter> plus minimale est analysée,

moins d'informations sont disponibles. Dans cet exemple, toutes les parties

temporelles sont renvoyées comme &false;.

<example>

<title>

<function>date_parse</function> avec

une chaîne minimale

</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">Les formats relatifs</link>

n'influencent pas les valeurs analysées depuis des formats absolus, mais

sont analysées dans l'élément "relatif".

<example>

<title>Exemple avec <function>date_parse</function> et des formats relatifs</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>

Certaines strophes, telles que <literal>Thursday</literal> (jeudi) définiront

la partie heure de la chaîne sur <literal>0</literal>. Si <literal>Thursday</literal>

(jeudi) est passé à <function>DateTimeImmutable::__construct</function> l'heure,

la minute, la seconde et la fraction seront également définies sur

<literal>0</literal>. Dans l'exemple ci-dessous, l'élément année

est cependant laissé à &false;.

<example>

<title><function>date_parse</function> avec des effets secondaires</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> pour analyser

le paramètre <parameter>datetime</parameter> avec un format spécifique</member>

<member><function>checkdate</function> pour une validation de date Grégorienne</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

-->