Wertet eine Zeitangabe gemäß dem angegebenen Format aus

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

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

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Wertet eine Zeitangabe gemäß dem angegebenen Format aus

### Beschreibung

Objektorientierter Stil

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

Prozeduraler Stil

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

Gibt ein neues DateTimeImmutable-Objekt zurück. Es stellt das Datum und die Uhrzeit dar, die in der Zeichenkette `datetime` angegeben sind und gemäß dem angegebenen `format` formatiert wurden.

### Parameter-Liste

`format`

  Das Format, in dem der übergebene String sein soll. Siehe die nachfolgenden Formatierungsoptionen. In den meisten Fällen können die gleichen Buchstaben verwendet werden wie für die Funktion date().

  Alle Felder werden mit den aktuellen Werten für Datum und Uhrzeit initialisiert. In den meisten Fällen wird man diese auf "Null" zurücksetzen wollen (die Unix-Epoche, `1970-01-01 00:00:00 UTC`). Dies wird erreicht, indem das Zeichen `!` als erstes Zeichen in den Parameter `format` eingefügt wird, oder `|` als letztes Zeichen. Weitere Informationen zu den einzelnen Zeichen sind in der folgenden Beschreibung zu finden.

  Das Format wird von links nach rechts ausgewertet, was bedeutet, dass die Reihenfolge, in der die Formatzeichen angeordnet sind, in manchen Situationen das Ergebnis beeinflusst. Im Fall von `z` (der Tag des Jahres) ist es erforderlich, dass bereits ein Jahr ausgewertet wurde, zum Beispiel durch die Zeichen `Y` oder `y`.

  Buchstaben, die für die Auswertung von Zahlen verwendet werden, lassen eine große Bandbreite von Werten zu, die außerhalb des logischen Bereichs liegen. Zum Beispiel akzeptiert das `d` (Tag des Monats) Werte im Bereich von `00` bis `99`. Die einzige Einschränkung betrifft die Anzahl der Ziffern. Wenn ein Wert außerhalb des Bereichs angegeben wird, wird der Überlaufmechanismus des Parsers für Datum und Uhrzeit verwendet. Im Folgenden sind einige Beispiele für dieses Überlaufverhalten aufgeführt.

  Das bedeutet auch, dass die Daten, die für einen Formatbuchstaben ausgewertet werden, gierig sind und so viele Ziffern lesen, wie ihr Format zulässt. Das kann dann auch bedeuten, dass in der Zeichenkette `datetime` nicht mehr genügend Zeichen für nachfolgende Formatzeichen vorhanden sind. Ein Beispiel auf dieser Seite veranschaulicht auch dieses Problem.

  Die folgenden Zeichen werden in der Parameterzeichenkette `format` erkannt
  `format`-Zeichen | Beschreibung | Beispiele zulässiger Werte
  --- | --- | ---
  Tag | --- | ---
  `d` und `j` | Tag des Monats; zwei Ziffern mit oder ohne vorangestellter Null | `01` bis `31` oder `1` bis `31` (2-stellige Zahlen, die höher sind als die Anzahl der Tage im Monat, werden akzeptiert, führen aber zu einem Überlauf des Monats. Zum Beispiel bedeutet die 33 bei Januar den 2. Februar)
  `D` und `l` | Textuelle Darstellung eines Tages | `Mon` bis `Sun` oder `Sonntag` bis `Samstag`. Wenn der angegebene Tagesname vom ausgewerteten (oder voreingestellten) Datum abweicht, kommt es zu einem Überlauf bis zum nächsten Datum mit dem angegebenen Tagesnamen. Siehe die Beispiele unten für eine Erklärung.
  `S` | Englisches Ordnungssuffix für einen Tag des Monats; zwei Buchstaben. Es wird bei der Auswertung ignoriert. | `st`, `nd`, `rd` oder `th`.
  `z` | Tag des Jahres (beginnend bei 0); es muss ein `Y` oder `y` vorangestellt werden. | `0` bis `365` (es können auch dreistellige Zahlen angegeben werden, die größer sind als die Anzahl der Tage in einem Jahr; in diesem Fall wird die Differenz auf das nächste Jahr übertragen. Zum Beispiel bedeutet 366 in Verbindung mit 2022 den 2. Januar 2023)
  Monat | --- | ---
  `F` und `M` | Textuelle Darstellung eines Monats, z. B. January oder Sept | `January` bis `December` oder `Jan` bis `Dec`
  `m` und `n` | Numerische Darstellung eines Monats; mit oder ohne vorangestellter Null | `01` bis `12` oder `1` bis `12` (es können auch zweistellige Zahlen größer als 12 angegeben werden; in diesem Fall wird die Differenz auf das nächste Jahr übertragen. Zum Beispiel bedeutet 13 den Januar des nächsten Jahres)
  Jahr | --- | ---
  `X` und `x` | Vollständige numerische Darstellung einer Jahreszahl; bis zu 19 Ziffern, optional mit vorangestelltem `+` oder `-` | Beispiele: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Vollständige numerische Darstellung einer Jahreszahl; bis zu vier Ziffern | Beispiele: `0055`, `787`, `1999`, `2003`
  `y` | Eine zweistellige Jahreszahl (für den Bereich 1970-2069). | Beispiele: `99` oder `03` (werden interpretiert als `1999` bzw. `2003`)
  Zeit | --- | ---
  `a` und `A` | Ante meridiem (vor Mittag) und post meridiem (nach Mittag) | `am` oder `pm`
  `g` und `h` | Stunde im 12-Stunden-Format; mit oder ohne vorangestellter Null | `1` bis `12` oder `01` bis `12` (es können auch zweistellige Zahlen größer als 12 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `14` bedeutet zum Beispiel `02` im nächsten AM/PM-Zeitraum)
  `G` und `H` | Stunde im 24-Stunden-Format; mit oder ohne vorangestellter Null | `0` bis `23` oder `00` bis `23` (es können auch zweistellige Zahlen größer als 24 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `26` bedeutet zum Beispiel `02:00` am nächsten Tag)
  `i` | Minuten; mit vorangestellter Null | `00` to `59` (es können auch zweistellige Zahlen größer als 59 angegeben werden; in diesem Fall wird die Differenz auf die nächste Stunde übertragen. `66` bedeutet zum Beispiel `:06` in der nächsten Stunde)
  `s` | Sekunden; mit vorangestellter Null | `00` bis `59` (es können auch zweistellige Zahlen größer als 59 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `90` bedeutet zum Beispiel `:30` in der nächsten Minute)
  `v` | Bruchteil in Millisekunden (bis zu drei Ziffern) | Beispiel: `12` (`0.12` Sekunden), `345` (`0.345` Sekunden)
  `u` | Bruchteil in Mikrosekunden (bis zu sechs Ziffern) | Beispiel: `45` (`0.45` Sekunden), `654321` (`0.654321` Sekunden)
  Zeitzone | --- | ---
  `e`, `O`, `p`, `P` und `T` | Bezeichner der Zeitzone, Differenz zu UTC (in Stunden), Differenz zu UTC (mit Doppelpunkt zwischen Stunden und Minuten) oder Zeitzonenkürzel | Beispiele: `UTC`, `GMT`, `Atlantic/Azores`, `+0200`, `+02:00`, `EST`, `MDT`
  Datum und Uhrzeit in voller Länge | --- | ---
  `U` | Sekunden seit der Unix-Epoche (1. Januar 1970 00:00:00 GMT) | Beispiel: `1292177455`
  Whitespace und Trennzeichen | --- | ---
  `` (Leerraum) | Leerzeichen, Tabulatoren, oder NBSP (U+A0)- oder NNBSP (U+202F)-Zeichen | Beispiele: `"\t"`, `" "`
  `#` | Eins der folgenden Trennzeichen: `;`, `:`, `/`, `.`, `,`, `-`, `(` oder `)` | Beispiel: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` oder `)` | Das angegebene Zeichen | Beispiel: `-`
  `?` | Ein beliebiges Byte | Beispiel: `^` (es ist zu beachten, dass für UTF-8-Zeichen möglicherweise mehr als ein `?` benötigt wird. In diesem Fall ist es wahrscheinlich besser, `*` zu verwenden)
  `*` | Beliebige Bytes bis zum nächsten Trennzeichen oder zur nächsten Ziffer | Beispiel: `*` in `Y-*-d` entspricht in Verbindung mit der Zeichenkette `2009-aWort-08` dem Wert `aWort`
  `!` | Setzt alle Felder (Jahr, Monat, Tag, Stunde, Minute, Sekunde, Bruchteil und Zeitzone) auf ihre Ausgangswerte zurück (`0` bei Stunde, Minute, Sekunde und Bruchteil; `1` bei Monat und Tag; `1970` bei Jahr und `UTC` bei der Zeitzone) | Ohne `!` werden alle Felder auf das aktuelle Datum und die aktuelle Uhrzeit gesetzt.
  `|` | Setzt die Werte der noch nicht ausgewerteten Felder (Jahr, Monat, Tag, Stunde, Minute, Sekunde, Zeitzone) auf ihre Ausgangswerte zurück | `Y-m-d|` setzt Jahr, Monat und Tag entsprechend der Informationen aus der ausgewerteten Zeichenkette und setzt Stunde, Minute und Sekunde auf 0
  `+` | Wenn dieses Formatzeichen verwendet wird, führen nachfolgende Daten in der Zeichenkette nicht zu einem Fehler, sondern zu einer Warnung | Um zu überprüfen, ob nachfolgende Daten vorhanden waren, kann DateTimeImmutable::getLastErrors() verwendet werden.

  Wenn die Formatzeichenkette Zeichen enthält, die nicht erkannt werden, schlägt die Auswertung fehl und es wird eine Fehlermeldung an die zurückgegebene Struktur angehängt. Die Fehlermeldungen können mit DateTimeImmutable::getLastErrors() abgefragt werden.

  Wenn literale Zeichen in `format` verwendet werden, müssen diese mit einem Backslash (`\`) maskiert werden.

  Wenn `format` nicht das Zeichen `!` enthält, werden die Teile des Datums und der Uhrzeit, die nicht in `format` angegeben sind, auf die aktuelle Systemzeit gesetzt.

  Wenn `format` das Zeichen `!` enthält, werden die Teile des Datums und der Uhrzeit, die nicht in `format` angegeben sind, sowie die Werte links von `!` auf die entsprechenden Werte der Unix-Epoche gesetzt.

  Wenn ein Zeichen der Uhrzeit ausgewertet wird, werden alle anderen zeitbezogenen Felder auf "0" gesetzt, sofern sie nicht ebenfalls ausgewertet werden.

  Die Unix-Epoche ist 1970-01-01 00:00:00 UTC.

`datetime`

  Eine Zeichenkette, die die Zeit angibt.

`timezone`

  Ein DateTimeZone-Objekt, das die gewünschte Zeitzone darstellt.

  Wenn `timezone` nicht angegeben wird oder `null` ist und `datetime` keine Zeitzone enthält, wird die aktuelle Zeitzone verwendet.

  > Hinweis:

  > Wenn der Parameter `datetime` entweder einen UNIX-Zeitstempel enthält (z. B. `946684800`) oder eine Zeitzone vorgibt (z. B. `2010-01-28T15:00:00+02:00`), werden der Parameter `timezone` und die aktuelle Zeitzone ignoriert.

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn der Parameter `datetime` NULL-Bytes enthält, wirft diese Methode einen ValueError.

### Changelog

Version | Beschreibung
--- | ---
8.2.9 | Das `` - (Leerraum) Zeichen unterstützt nun auch die Zeichen NBSP (U+A0) und NNBSP (U+202F).
8.2.0 | Die `format`-Zeichen `X` und `x` wurden hinzugefügt.
8.0.21, 8.1.8, 8.2.0 | Wenn in `datetime` NULL-Bytes übergeben werden, wird nun ein ValueError geworfen; vorher wurde dies stillschweigend ignoriert.
7.3.0 | Das `format`-Zeichen `v` wurde hinzugefügt.

### Beispiele

Beispiel #1 DateTimeImmutable::createFromFormat()-Beispiel

Objektorientierter Stil

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

Beispiel #2 Verwendung von DateTimeImmutable::createFromFormat() mit vordefinierten Formatkonstanten

Objektorientierter Stil

    <?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');
    ?>

Die in diesem Beispiel verwendeten Formatierungskonstanten bestehen aus einer Reihe von Zeichen für die Formatierung eines DateTimeImmutable-Objekts. In den meisten Fällen stimmen diese Buchstaben mit den entsprechenden Elementen der Datums-/Zeitinformationen überein, wie sie im obigen Abschnitt parameters definiert sind, aber sie sind in der Regel etwas weniger strikt.

Beispiel #3 Besonderheiten von DateTimeImmutable::createFromFormat()

    <?php
    echo 'Aktuelle Zeit: ' . 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";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Aktuelle Zeit: 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

Beispiel #4 Formatzeichenkette mit literalen Zeichen

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

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    23:15:03

Beispiel #5 Verhalten bei einem Überlauf

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

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

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

Das Ergebnis sieht zwar merkwürdig aus, ist aber korrekt, da die folgenden Überläufe erfolgen:

1. `97` Sekunden überschreiten `1` Minute, sodass `37` Sekunden übrig bleiben.
2. `61` Minuten überschreiten `1` Stunde, sodass `1` Minute übrig bleibt.
3. `35` Tage überschreiten `1` Monat, sodass `4` Tage übrig bleiben. Da nicht jeder Monat die gleiche Anzahl von Tagen hat, hängt die Anzahl der Tage, die übrig bleiben, vom Monat ab.
4. `18` Monate überschreiten `1` Jahr, sodass `6` Monate übrig bleiben.

Beispiel #6 Verhalten bei überlaufenden Tagesnamen

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

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

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

Das Ergebnis sieht zwar merkwürdig aus, ist aber korrekt, da die folgenden Überläufe erfolgen:

1. `3 Aug 2020 25:00:00` geht über in `(Tue) 4 Aug 2020 01:00`.
2. `Mon` wird eingesetzt, was das Datum auf `Mon, 10 Aug 2020 01:00:00` vorverlegt. Relative Schlüsselwörter wie `Mon` werden im Abschnitt über relative Formate erläutert.

Um Überläufe in Daten zu erkennen, kann die Methode DateTimeImmutable::getLastErrors() verwendet werden, die eine Warnung enthält, wenn ein Überlauf aufgetreten ist.

Beispiel #7 Erkennen von übergelaufenen Daten

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

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

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

Beispiel #8 Gieriges Verhalten beim Auswerten

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

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

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

Das Format `G` dient der Auswertung von Uhrzeiten im 24-Stunden-Format, mit oder ohne vorangestellter Null. Dies erfordert die Analyse von 1 oder 2 Ziffern. Da zwei Ziffern folgen, wird dies gierig als `60` gelesen.

Die folgenden Formatzeichen `i` und `s` benötigen beide zwei Ziffern. Das bedeutet, dass `10` als Minute (`i`) übergeben wird, und dass dann nicht mehr genug Ziffern übrig sind, um sie als Sekunde (`s`) zu verarbeiten.

Das Array `errors` zeigt dieses Problem an.

Außerdem liegt der Wert `60` für die Stunde außerhalb des Bereichs `0`-`24`, was dazu führt, dass das Array `warnings` eine Warnung enthält, dass die Zeit ungültig ist.

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt
- DateTimeImmutable::getLastErrors() - Liefert die Warnungen und Fehler
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit
- strptime() - Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde

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