<?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>Analyse une heure au format texte selon le format spécifié.

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

Retourne un nouvel objet <classname>DateTimeImmutable</classname>

représentant la date et l'heure spécifiées par la chaîne

<parameter>datetime</parameter>, qui a été formatée au

<parameter>format</parameter> donné.

</para>

</refsect1>

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

&reftitle.parameters;

<variablelist>

<varlistentry>

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

<listitem>

<para>

Le format dans lequel <type>string</type> doit être transmise. Voir les

options de formatage ci-dessous. Dans la plupart des cas, les mêmes lettres

que pour la <function>date</function> peuvent être utilisées.

</para>

<para>

Tous les champs sont initialisés avec la date/heure actuelle. Dans la

plupart des cas, l'on voudra les remettre à "zéro" (l'époque Unix,

<literal>1970-01-01 00:00:00 UTC</literal>). Il est possible de faire cela

en incluant le caractère <literal>!</literal> comme premier caractère dans

<parameter>format</parameter>, ou <literal>|</literal> comme dernier.

Consulter la documentation de chaque caractère ci-dessous pour

plus d'informations.

</para>

<para>

Le format est analysé de gauche à droite, ce qui signifie que dans

certaines situations, l'ordre dans lequel les caractères de format

sont présents affecte le résultat. Dans le cas de <literal>z</literal>

(le jour de l'année), il est nécessaire qu'une année ait déjà été analysée,

par exemple via les caractères <literal>Y</literal> ou <literal>y</literal>.

</para>

<para>

Les lettres utilisées pour l'analyse des nombres autorisent une large plage

de valeurs, en dehors de ce que serait la plage logique. Par exemple,

le <literal>d</literal> (jour du mois) accepte des valeurs comprises entre

<literal>00</literal> et <literal>99</literal>. La seule contrainte est sur

le nombre de chiffres. Le mécanisme de débordement de l'analyseur date/heure

est utilisé lorsque des valeurs hors plage sont données. Les exemples

ci-dessous illustrent certains de ces comportements.

</para>

<para>

Cela signifie également que les données analysées pour une lettre de format

sont gourmandes et liront jusqu'au nombre de chiffres que son format autorise.

Cela peut également signifier qu'il n'y a plus assez de caractères dans la chaîne

<parameter>datetime</parameter> pour les caractères de format suivants. Un exemple

plus bas sur cette page illustre également ce problème.

</para>

<para>

<table>

<title>Les caractères suivants sont reconnus pour le paramètre

<parameter>format</parameter></title>

<tgroup cols="3">

<thead>

<row>

<entry>Caractère de <parameter>format</parameter></entry>

<entry>Description</entry>

<entry>Exemple de valeurs analysées</entry>

</row>

</thead>

<tbody>

<row>

<entry align="center"><emphasis>Jour</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>d</literal> et <literal>j</literal></entry>

<entry>Jour du mois, sur 2 chiffres, avec ou sans le zéro initial</entry>

<entry>

<literal>01</literal> à <literal>31</literal> ou

<literal>1</literal> à <literal>31</literal> (les nombres à 2

chiffres supérieurs au nombre de jours du mois sont acceptés,

auquel cas ils feront déborder le mois. Par exemple utiliser

33 avec janvier, signifiera le 2 février)

</entry>

</row>

<row>

<entry><literal>D</literal> et <literal>l</literal></entry>

<entry>Une représentation textuelle du jour</entry>

<entry>

De <literal>Mon</literal> jusqu'à <literal>Sun</literal> ou

de <literal>Sunday</literal> jusqu'à <literal>Saturday</literal>

Si le nom de jour donné est différent alors le nom de jour

appartenant à une date analysée (ou par défaut) est différent,

alors un débordement se produit vers la date

<emphasis>suivante</emphasis> avec le nom de jour donné.

Voir les exemples ci-dessous pour une explication.

</entry>

</row>

<row>

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

<entry>Préfixe anglais du jour du mois, sur 2 caractères.

Il sera ignoré lors de l'analyse.</entry>

<entry>

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

<literal>th</literal>.

</entry>

</row>

<row>

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

<entry>

Le jour de l'année (en commençant à 0);

doit être précédé par <literal>Y</literal> ou <literal>y</literal>.

</entry>

<entry>

<literal>0</literal> à <literal>365</literal>

(les nombres à 3 chiffres supérieurs aux nombres d'une année sont

acceptés, auquel cas ils feront déborder l'année. Par exemple,

utiliser 366 avec 2022, signifie le 2 janvier 2023)

</entry>

</row>

<row>

<entry align="center"><emphasis>Mois</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>F</literal> et <literal>M</literal></entry>

<entry>Une représentation textuelle du mois, comme January ou Sept</entry>

<entry>

De <literal>January</literal> à <literal>December</literal> ou

de <literal>Jan</literal> à <literal>Dec</literal>

</entry>

</row>

<row>

<entry><literal>m</literal> et <literal>n</literal></entry>

<entry>Une représentation numérique du mois, avec ou sans zéro initial</entry>

<entry>

De <literal>01</literal> à <literal>12</literal> ou

de <literal>1</literal> à <literal>12</literal>

(les nombres à 2 chiffres supérieurs à 12 sont acceptés, auquel cas ils

feront déborder l'année. Par exemple, utiliser 13 signifie janvier de

l'année suivante)

</entry>

</row>

<row>

<entry align="center"><emphasis>Année</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>X</literal> et <literal>x</literal></entry>

<entry>

Une représentation numérique complète d'une année,

<emphasis>jusqu'à</emphasis> 19 chiffres, éventuellement préfixée par

<literal>+</literal> ou <literal>-</literal>

</entry>

<entry>Exemples : <literal>1999</literal> ou <literal>2003</literal></entry>

</row>

<row>

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

<entry>Une représentation complète de l'année, <emphasis>jusqu'à</emphasis> 4 chiffres</entry>

<entry>Exemples: <literal>25</literal> (comme <literal>0025</literal>),

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

</row>

<row>

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

<entry>Une représentation partielle de l'année, sur 2 chiffres

(qui doit être dans l'intervalle 1970-2069, inclus)</entry>

<entry>

Exemples :

<literal>99</literal> ou <literal>03</literal>

(seront interprétés comme l'année <literal>1999</literal> et l'année

<literal>2003</literal>, respectivement)

</entry>

</row>

<row>

<entry align="center"><emphasis>Heure</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal>a</literal> et <literal>A</literal></entry>

<entry>Ante meridiem et Post meridiem</entry>

<entry><literal>am</literal> ou <literal>pm</literal></entry>

</row>

<row>

<entry><literal>g</literal> et <literal>h</literal></entry>

<entry>L'heure au format 12-heures, avec ou sans zéro initial</entry>

<entry>

De <literal>1</literal> à <literal>12</literal> ou

de <literal>01</literal> à <literal>12</literal>

(les nombres à 2 chiffres supérieurs à 12 sont acceptés,

auquel cas ils feront déborder le jour. Par exemple

utiliser 14 signifie 02 dans la prochaine période AM/PM)

</entry>

</row>

<row>

<entry><literal>G</literal> et <literal>H</literal></entry>

<entry>L'heure au format 24-heures, avec ou sans zéro initial</entry>

<entry>

De <literal>0</literal> à <literal>23</literal> ou

de <literal>00</literal> à <literal>23</literal>

(les nombres à 2 chiffres supérieurs à 24 sont acceptés,

auquel cas ils feront déborder la journée. Par exemple

utiliser 26 signifie 02:00 le lendemain)

</entry>

</row>

<row>

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

<entry>Les minutes, avec un zéro initial</entry>

<entry>

De <literal>00</literal> à <literal>59</literal>

(les nombres à 2 chiffres supérieurs à 59 sont acceptés,

auquel cas ils feront déborder l'heure. Par exemple

utiliser 66 signifie :06 l'heure suivante)

</entry>

</row>

<row>

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

<entry>Les secondes, avec un zéro initial</entry>

<entry>

De <literal>00</literal> à <literal>59</literal>

(les nombres à 2 chiffres supérieurs à 59 sont acceptés,

auquel cas ils feront déborder la minute. Par exemple

utiliser 90 signifie :30 la minute suivante)

</entry>

</row>

<row>

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

<entry>Les millisecondes (jusqu'à 3 chiffres)</entry>

<entry>

Exemple: <literal>12</literal> (<literal>0.12</literal>

secondes), <literal>345</literal> (<literal>0.345</literal>

secondes)

</entry>

</row>

<row>

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

<entry>Les microsecondes (jusqu'à 6 chiffres)</entry>

<entry>

Exemple : <literal>45</literal> (<literal>0.45</literal>

secondes), <literal>654321</literal> (<literal>

0.654321</literal> secondes)

</entry>

</row>

<row>

<entry align="center"><emphasis>Fuseau horaire</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry>

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

<literal>P</literal> et <literal>T</literal>

</entry>

<entry>L'identifiant du fuseau horaire, ou la différence en heures avec UTC,

ou la différence avec UTC avec deux points (:) entre les heures et les minutes,

ou l'abréviation du fuseau horaire</entry>

<entry>Exemples : <literal>UTC</literal>, <literal>GMT</literal>,

<literal>Atlantic/Azores</literal> ou

<literal>+0200</literal> ou <literal>+02:00</literal> ou

<literal>EST</literal>, <literal>MDT</literal>

</entry>

</row>

<row>

<entry align="center"><emphasis>Date/heure complète</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

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

<entry>Le nombre de secondes depuis l'époque Unix (1er janvier 1970 00:00:00 GMT)</entry>

<entry>Exemple : <literal>1292177455</literal></entry>

</row>

<row>

<entry align="center"><emphasis>Espace et séparateurs</emphasis></entry>

<entry>---</entry>

<entry>---</entry>

</row>

<row>

<entry><literal> </literal> (espace)</entry>

<entry>Zéro ou plusieurs espaces, tabulations, caractères NBSP (U+A0), ou NNBSP (U+202F)</entry>

<entry>Exemple: <literal>"\t"</literal>, <literal>" "</literal></entry>

</row>

<row>

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

<entry>

Un des symboles de séparation suivants : <literal>;</literal>,

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

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

<literal>)</literal>

</entry>

<entry>Exemple : <literal>/</literal></entry>

</row>

<row>

<entry>

<literal>;</literal>,

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

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

<literal>)</literal>

</entry>

<entry>Le caractère spécifié.</entry>

<entry>Exemple : <literal>-</literal></entry>

</row>

<row>

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

<entry>Un octet aléatoire</entry>

<entry>

Exemple : <literal>^</literal> (Il est à noter que pour les

caractères UTF-8, l'on pourrait avoir besoin de plus d'un

<literal>?</literal>. Dans ce cas, utiliser <literal>*</literal>

est probablement ce que l'on veut à la place)

</entry>

</row>

<row>

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

<entry>Octets aléatoires jusqu'au prochain séparateur ou chiffre</entry>

<entry>Exemple : <literal>*</literal> dans <literal>Y-*-d</literal> avec la chaîne

<literal>2009-aWord-08</literal> trouvera la chaîne

<literal>aWord</literal></entry>

</row>

<row>

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

<entry>

Réinitialise tous les champs (année, mois, jour, heure, minute,

seconde ainsi que les informations quant au fuseau horaire) à

des valeurs similaires à zéro (<literal>0</literal> pour heure,

minute, seconde et fraction, <literal>1</literal> pour mois et jour,

<literal>1970</literal> pour l'année et le fuseau horaire par défaut)

</entry>

<entry>Sans le caractère <literal>!,</literal> tous les champs seront

définis à la date et heure courante.</entry>

</row>

<row>

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

<entry>Réinitialise tous les champs (année, mois, jour, heure, minute,

seconde ainsi que les informations quant au fuseau horaire) à

valeurs similaires à zéro s'ils n'ont pas encore été analysés</entry>

<entry><literal>Y-m-d|</literal> définira l'année, le mois et le jour

avec les informations trouvées dans la chaîne analysée, mais aussi

l'heure, les minutes et les secondes à 0.</entry>

</row>

<row>

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

<entry>Si le spécifieur de format est présent, les données restantes

de la chaîne ne causeront pas une erreur, mais une alerte</entry>

<entry>Utiliser la méthode <methodname>DateTime::getLastErrors</methodname>

pour identifier la présence de données restantes.</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

<para>

Les caractères non reconnus dans la chaîne de format entraîneront

l'échec de l'analyse et un message d'erreur est ajouté à la structure

renvoyée. Il est possible d'interroger les messages d'erreur avec

<methodname>DateTimeImmutable::getLastErrors</methodname>.

</para>

<para>

Pour inclure un caractère littéral dans <parameter>format</parameter>,

il faut l'échapper avec un antislash (<literal>\</literal>).

</para>

<para>

Si <parameter>format</parameter> n'est pas composé du caractère

<literal>!</literal> alors les valeurs de temps générées qui sont absentes de

<parameter>format</parameter> prendront comme valeur le temps système.

</para>

<para>

Si <parameter>format</parameter> contient le caractère

<literal>!</literal>, alors les valeurs de temps générées qui sont absentes de

<parameter>format</parameter> ainsi que les valeurs situées à gauche de

<literal>!</literal> prendront des valeurs mesurées depuis l'époque Unix.

</para>

<para>

Si un caractère de temps est analysé, alors tous les autres champs liés au

temps sont mis à "0", sauf s'ils sont également analysés.

</para>

<para>

Le début de l'époque Unix est le 01/01/1970 à 00:00:00 UTC.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Chaîne représentant le moment.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Un objet <classname>DateTimeZone</classname> représentant

le fuseau horaire désiré.

</para>

<para>

Si <parameter>timezone</parameter> est omis ou &null; et

<parameter>datetime</parameter> ne contient pas de fuseau,

le fuseau courant sera utilisé.

</para>

<note>

<para>

Le paramètre <parameter>timezone</parameter> et le fuseau

courant sont ignorés lorsque le paramètre

<parameter>datetime</parameter> contient un timestamp

(p. ex. <literal>946684800</literal>) ou précise un fuseau

(p. ex. <literal>2010-01-28T15:00:00+02:00</literal>).

</para>

</note>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Retourne un nouvel objet <classname>DateTimeImmutable</classname>&return.falseforfailure;.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

Cette méthode lance une <exceptionname>ValueError</exceptionname> lorsque le

<parameter>datetime</parameter> contient des octets NULL.

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

Le spécificateur <literal> </literal> (espace) prend désormais également

en charge les caractères NBSP (U+A0) et NNBSP (U+202F).

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

Les spécificateurs <literal>X</literal> et <literal>x</literal>

<parameter>format</parameter> ont été ajoutés.

</entry>

</row>

<row>

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

<entry>

Lance désormais une <exceptionname>ValueError</exceptionname> lorsque des octets NULL

sont passés dans <parameter>datetime</parameter>, ce qui était auparavant ignoré

silencieusement.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Le spécificateur de <parameter>format</parameter> <literal>v</literal> a été ajouté.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title>Exemple avec <function>DateTimeImmutable::createFromFormat</function></title>

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

<programlisting role="php">

</programlisting>

</example>

<example>

<title>Utilisation des constantes de format prédéfinies avec <function>DateTimeImmutable::createFromFormat</function></title>

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

<programlisting role="php">

</programlisting>

<para>

Les <link linkend="datetimeinterface.constants.types">constantes de formatage</link>

telles qu'elles sont utilisées dans cet exemple consistent en

une chaîne de caractères pour <link linkend="datetime.format">formater</link> un

objet <classname>DateTimeImmutable</classname>. Dans la plupart des cas, ces

lettres correspondent aux mêmes éléments d'information sur la date et l'heure

que ceux définis dans la section <link

linkend="datetimeimmutable.createfromformat.parameters">paramètres</link>

ci-dessus, mais elles ont tendance à être plus indulgentes.

</para>

</example>

<example>

<title>Les subtilités de <function>DateTimeImmutable::createFromFormat</function></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Texte de Format avec des caractères littéraux</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Comportement de débordement</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Bien que le résultat semble étrange, il est correct,

car les débordements suivants se produisent:

</para>

<orderedlist>

<listitem>

<simpara>

<literal>97</literal> secondes débordent sur <literal>1</literal> minute,

ce qui laisse <literal>37</literal> secondes.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>61</literal> minutes débordent sur <literal>1</literal> heure,

ce qui laisse <literal>1</literal> minute.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>35</literal> jours débordent sur <literal>1</literal> mois,

ce qui laisse <literal>4</literal> jours. Le nombre de jours restants

dépend du mois, car tous les mois n'ont pas le même nombre de jours.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>18</literal> mois débordent sur <literal>1</literal> an,

ce qui laisse <literal>6</literal> mois.

</simpara>

</listitem>

</orderedlist>

</example>

<example>

<title>Comportement pour le nom de jour débordant</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Bien que le résultat semble étrange, il est correct,

car les débordements suivants se produisent:

</para>

<orderedlist>

<listitem>

<simpara>

<literal>3 Aug 2020 25:00:00</literal> débordent sur <literal>(Tue) 4 Aug

2020 01:00</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

<literal>Mon</literal> est appliqué, ce qui avance la date au

<literal>Mon, 10 Aug 2020 01:00:00</literal>. L'explication des

mots-clés relatifs tels que <literal>Mon</literal> est expliquée

dans la section sur les <link linkend="datetime.formats.relative">

formats relatifs</link>.

</simpara>

</listitem>

</orderedlist>

</example>

<para>

Afin de détecter les dépassements de dates, il est possible d'utiliser

<methodname>DateTimeImmutable::getLastErrors</methodname>, qui

inclura un avertissement en cas de dépassement.

</para>

<example>

<title>Détecter les dates dépassées</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

<example>

<title>Comportement d'analyse gourmand</title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

<para>

Le format <literal>G</literal> consiste à analyser les heures d'horloge

sur 24 heures, avec ou sans zéro de tête. Cela nécessite d'analyser 1 ou 2

chiffres. Parce qu'il y a deux chiffres suivants, il lit avidement cela

comme <literal>60</literal>.

</para>

<para>

Les caractères de format <literal>i</literal> et <literal>s</literal> suivants

nécessitent tous deux deux chiffres. Cela signifie que <literal>10</literal>

est passé comme minute (<literal>i</literal>), et qu'il n'y a alors plus assez

de chiffres à analyser comme seconde (<literal>s</literal>).

</para>

<para>

Le tableau <literal>errors</literal> indique ce problème.

</para>

<para>

De plus, une heure de <literal>60</literal> est en dehors de la plage

<literal>0</literal>-<literal>24</literal>, ce qui fait que le tableau

<literal>warnings</literal> inclut un avertissement indiquant que l'heure n'est pas

valide.

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