DateTimeImmutable::createFromFormat

>(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Analyse une heure au format texte selon le format spécifié.

Description

Style orienté objet

Style procédural

Retourne un nouvel objet DateTimeImmutable représentant la date et l'heure spécifiées par la chaîne datetime, qui a été formatée au format donné.

Liste de paramètres

format

Le format dans lequel string doit être transmise. Voir les options de formatage ci-dessous. Dans la plupart des cas, les mêmes lettres que pour la date() peuvent être utilisées.

Tous les champs sont initialisés avec la date/heure actuelle. Dans la plupart des cas, vous voudrez les remettre à "zéro" (l'époque Unix, 1970-01-01 00:00:00 UTC). Vous pouvez faire cela en incluant le caractère ! comme premier caractère dans format, ou | comme dernier. Veuillez consulter la documentation de chaque caractère ci-dessous pour plus d'informations.

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 z (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 Y ou y.

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 d (jour du mois) accepte des valeurs comprises entre 00 et 99. 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.

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 datetime pour les caractères de format suivants. Un exemple plus bas sur cette page illustre également ce problème.

Les caractères suivants sont reconnus pour le paramètre format

format character	Description	Exemple de valeurs analysées
Jour	---	---
d et j	Jour du mois, sur 2 chiffres, avec ou sans le zéro initial	01 à 31 ou 1 à 31 (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)
D and l	Une représentation textuelle du jour	De Mon jusqu'à Sun ou de Sunday jusqu'à Saturday 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 suivante avec le nom de jour donné. Voir les exemples ci-dessous pour une explication.
S	Préfixe anglais du jour du mois, sur 2 caractères. Il sera ignoré lors de l'analyse.	st, nd, rd ou th.
z	Le jour de l'année (en commençant à 0); doit être précédé par Y ou y.	0 à 365 (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)
Mois	---	---
F et M	Une représentation textuelle du mois, comme January ou Sept	De January à December ou de Jan à Dec
m et n	Une représentation numérique du mois, avec ou sans zéro initial	De 01 à 12 ou de 1 à 12 (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)
Année	---	---
X et x	Une représentation numérique complète d'une année, jusqu'à 19 chiffres, éventuellement préfixée par + ou -	Exemples : 1999 ou 2003
Y	Une représentation complète de l'année, sur 4 chiffres	Exemples : 0055, 787, 1999, -2003, +10191
y	Une représentation partielle de l'année, sur 2 chiffres (qui doit être dans l'intervalle 1970-2069, inclus)	Exemples : 99 ou 03 (seront interprétés comme l'année 1999 et l'année 2003, respectivement)
Heure	---	---
a et A	Ante meridiem et Post meridiem	am ou pm
g et h	L'heure au format 12-heures, avec ou sans zéro initial	De 1 à 12 ou de 01 à 12 (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)
G et H	L'heure au format 24-heures, avec ou sans zéro initial	De 0 à 23 ou de 00 à 23 (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)
i	Les minutes, avec un zéro initial	De 00 à 59 (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)
s	Les secondes, avec un zéro initial	De 00 à 59 (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)
v	Les millisecondes (jusqu'à 3 chiffres)	Exemple: 12 (0.12 secondes), 345 (0.345 secondes)
u	Les microsecondes (jusqu'à 6 chiffres)	Exemple : 45 (0.45 secondes), 654321 ( 0.654321 secondes)
Fuseau horaire	---	---
e, O, P et T	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	Exemples : UTC, GMT, Atlantic/Azores ou +0200 ou +02:00 ou EST, MDT
Date/heure complète	---	---
U	Le nombre de secondes depuis l'époque Unix (January 1 1970 00:00:00 GMT)	Exemple : 1292177455
Espace et séparateurs	---	---
(espace)	Un espace ou une tabulation	Exemple :
#	Un des symboles de séparation suivants : ;, :, /, ., ,, -, ( ou )	Exemple : /
;, :, /, ., ,, -, ( ou )	Le caractère spécifié.	Exemple : -
?	Un octet aléatoire	Exemple : ^ (Sachez que pour les caractères UTF-8, vous pourriez avoir besoin de plus d'un ?. Dans ce cas, utiliser * est probablement ce que vous voulez à la place)
*	Octets aléatoires jusqu'au prochain séparateur ou chiffre	Exemple : * dans Y-*-d avec la chaîne 2009-aWord-08 trouvera la chaîne aWord
!	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 (0 pour heure, minute, seconde et fraction, 1 pour mois et jour, 1970 pour l'année et UTC pour l'information de fuseau horaire)	Sans le caractère !, tous les champs seront définis à la date et heure courante.
|	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	Y-m-d| 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.
+	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	Utilisez la méthode datetime::getLastErrors() pour identifier la présence de données restantes.

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. Vous pouvez interroger les messages d'erreur avec datetimeimmutable::getLastErrors().

Pour inclure un caractère littéral dans format, vous devez l'échapper avec un antislash (\).

Si format n'est pas composé du caractère ! alors les valeurs de temps générées qui sont absentes de format prendront comme valeur le temps système.

Si format contient le caractère !, alors les valeurs de temps générées qui sont absentes de format ainsi que les valeurs situées à gauche de ! prendront des valeurs mesurées depuis l'époque Unix.

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

datetime

Chaîne représentant le moment.

timezone

Un objet DateTimeZone représentant le fuseau horaire désiré.

Si timezone est omis ou null et datetime ne contient pas de fuseau, le fuseau courant sera utilisé.

Note:

Le paramètre timezone et le fuseau courant sont ignorés lorsque le paramètre datetime contient un timestamp (e.g. 946684800) ou précise un fuseau (e.g. 2010-01-28T15:00:00+02:00).

Valeurs de retour

Retourne un nouvel objet DateTimeImmutable ou false si une erreur survient.

Historique

Exemples

Exemple #1 Exemple avec DateTimeImmutable::createFromFormat()

Style orienté objet

Exemple #2 Utilisation des constantes de format prédéfinies avec DateTimeImmutable::createFromFormat()

Style orienté objet

Les constantes de formatage utilisées dans cet exemple consistent en une chaîne de caractères pour formater un objet DateTimeImmutable. 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 parameters ci-dessus, mais elles ont tendance à être plus indulgentes. Les constantes de formatage telles qu'elles sont utilisées dans cet exemple consistent en une chaîne de caractères pour formater un objet DateTimeImmutable. 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 paramètres ci-dessus, mais elles ont tendance à être plus faciles à utiliser.

Exemple #3 Les subtilités de DateTimeImmutable::createFromFormat()

Résultat de l'exemple ci-dessus est similaire à :

Date courante: 2022-06-02 15:50:46
Format: Y-m-d; 2009-02-15 15:50:46
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
Format: !d; 1970-01-15 00:00:00
Format: i; 2022-06-02 00:15:00

Exemple #4 Texte de Format avec des caractères litéraux

Résultat de l'exemple ci-dessus est similaire à :

23:15:03

Exemple #5 Comportement de débordement

Résultat de l'exemple ci-dessus est similaire à :

Sat, 04 Jun 2022 17:01:37 +0000

Bien que le résultat semble étrange, il est correct, car les débordements suivants se produisent:

Exemple #6 Comportement pour le nom de jour débordant

Résultat de l'exemple ci-dessus est similaire à :

Mon, 10 Aug 2020 01:00:00 +0000

Bien que le résultat semble étrange, il est correct, car les débordements suivants se produisent:

Afin de détecter les dépassements de dates, vous pouvez utiliser datetimeimmutable::getLastErrors(), qui inclura un avertissement en cas de dépassement.

Exemple #7 Détecter les dates dépassées

Résultat de l'exemple ci-dessus est similaire à :

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) {
  }
}

Exemple #8 Comportement d'analyse gourmand

Résultat de l'exemple ci-dessus est similaire à :

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] =>
)

Le format G 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 60.

Les caractères de format i et s suivants nécessitent tous deux deux chiffres. Cela signifie que 10 est passé comme minute (i), et qu'il n'y a alors plus assez de chiffres à analyser comme seconde (s).

Le tableau errors indique ce problème.

De plus, une heure de 60 est en dehors de la plage 0-24, ce qui fait que le tableau warnings inclut un avertissant que l'heure n'est pas valide.

Voir aussi

• DateTimeImmutable::__construct() - Retourne un nouvel objet DateTimeImmutable
• datetimeimmutable::getLastErrors() - Retourne les alertes et erreurs
• checkdate() - Valide une date grégorienne
• strptime() - Analyse une date générée par strftime