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

Prozeduraler Stil

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:

97 Sekunden überschreiten 1 Minute, sodass 37 Sekunden übrig bleiben.
61 Minuten überschreiten 1 Stunde, sodass 1 Minute übrig bleibt.
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.
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:

3 Aug 2020 25:00:00 geht über in (Tue) 4 Aug 2020 01:00.
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

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 3 notes

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

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

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
}
```

＋add a note