Analyse une heure au format texte selon le format spécifié.

# 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 function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Style procédural

function 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, l'on voudra les remettre à "zéro" (l'époque Unix, `1970-01-01 00:00:00 UTC`). Il est possible de faire cela en incluant le caractère `!` comme premier caractère dans `format`, ou `|` comme dernier. 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`
  Caractère de `format` | 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` et `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 : `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Une représentation complète de l'année, jusqu'à 4 chiffres | Exemples : `25` (comme `0025`), `787`, `1999`, `2003`
  `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`, `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 (1er janvier 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 : `^` (Il est à noter que pour les caractères UTF-8, l'on pourrait avoir besoin de plus d'un `?`. Dans ce cas, utiliser `*` est probablement ce que l'on veut à 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 les informations 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 | Utiliser 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. Il est possible d'interroger les messages d'erreur avec DateTimeImmutable::getLastErrors().

  Pour inclure un caractère littéral dans `format`, il faut 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.

  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.

  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 (p. ex. `946684800`) ou précise un fuseau (p. ex. `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 de `format` `X` et `x` 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'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

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 indulgentes.

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 Chaîne de format avec des caractères litté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, il est possible d'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 avertissement indiquant 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open