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)	Zéro ou plusieurs espaces, tabulations, caractères NBSP (U+A0), ou NNBSP (U+202F)	Exemple: `"\t"`, `" "`
`#`	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.

Erreurs / Exceptions

Cette méthode lance une ValueError lorsque le datetime contient des octets NULL.

Historique

Version	Description
8.2.9	Le spécificateur (espace) prend désormais également en charge les caractères NBSP (U+A0) et NNBSP (U+202F).
8.2.0	Les spécificateurs `X` et `x` `format` ont été ajoutés.
8.0.21, 8.1.8, 8.2.0	Lance désormais une ValueError lorsque des octets NULL sont passés dans `datetime`, ce qui était auparavant ignoré silencieusement.
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:

97 secondes débordent sur 1 minute, ce qui laisse 37 secondes.
61 minutes débordent sur 1 heure, ce qui laisse 1 minute.
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.
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:

3 Aug 2020 25:00:00 débordent sur (Tue) 4 Aug 2020 01:00.
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

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

add a note

User Contributed Notes 3 notes

down

peter dot labos at gmail dot com ¶

11 months ago


If you are not happy with wide range of conversions and repairs this method is making for you, or just want to check that date is really same as input:

```
$datetime = \DateTimeImmutable::createFromFormat('Y-m-d G:i:s', $userDateTimeInput);

if ($datetime && $datetime->format('Y-m-d G:i:s') === $userDateTimeInput) {
  // $datetime is not false and we have a correct date in correct format from user
}
```

down

Tessa at AuRiseCreative dot com ¶

10 months ago


Since the description and examples don't exactly match for the timezone row, I want to clarify exactly which format each character outputs.

`e` outputs the timezone identifier, e.g. `America/New_York` or `Asia/Gaza`

`O` outputs the difference to UTC in hours, e.g. `-0500` or `+0200`

`P` outputs difference to UTC with a colon between hours and minutes, e.g. `-05:00` or `+02:00`

`T` outputs the timezone abbreviation, e.g. `EST` or `EET`

down

Andy Walker ¶

2 years ago


To clarify, g/G are 12/24 hour time without a leading 0, and h/H are 12/24 hour time with a leading zero, as described here:

https://www.php.net/manual/en/datetime.format.php

add a note