DateTimeImmutable::createFromFormat

date_create_immutable_from_format

(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

public static DateTimeImmutable::createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false

Style procédural

date_create_immutable_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false

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

Version Description
8.2.0 Les spécificateurs X et x format ont été ajoutés.
7.3.0 Le spécificateur de format v a été ajouté.

Exemples

Exemple #1 Exemple avec DateTimeImmutable::createFromFormat()

Style orienté objet

<?php
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>

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

Style orienté objet

<?php
$date = DateTimeImmutable::createFromFormat(DateTimeInterface::ISO8601, '2004-02-12T15:19:21+00:00');
$date = DateTimeImmutable::createFromFormat(DateTimeInterface::RFC3339_EXTENDED, '2013-10-14T09:00:00.000+02:00');
?>

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()

<?php
echo 'Date courante: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'i';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>

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

<?php
echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
?>

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

23:15:03

Exemple #5 Comportement de débordement

<?php
echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);
?>

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:

  1. 97 secondes débordent sur 1 minute, ce qui laisse 37 secondes.
  2. 61 minutes débordent sur 1 heure, ce qui laisse 1 minute.
  3. 35 jours débordent sur 1 mois, ce qui laisse 4 jours. Le nombre de jours restants dépend du mois, car tous les mois n'ont pas le même nombre de jours.
  4. 18 mois débordent sur 1 an, ce qui laisse 6 mois.

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

<?php
$d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
echo $d->format(DateTime::RFC1123), "\n";
?>

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:

  1. 3 Aug 2020 25:00:00 débordent sur (Tue) 4 Aug 2020 01:00.
  2. Mon est appliqué, ce qui avance la date au Mon, 10 Aug 2020 01:00:00.L'explication des mots-clés relatifs tels que Mon est expliquée dans la section sur les formats relatifs.

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

<?php
$d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

var_dump(DateTimeImmutable::GetLastErrors());
?>

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

<?php
print_r(date_parse_from_format('Gis', '60101'));
?>

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