DateTimeImmutable::createFromFormat

date_create_immutable_from_format

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

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Розбирає рядок з датою згідно з вказаним форматом

Опис

Об'єктно-орієнтований стиль

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

Процедурний стиль

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

Повертає новий об'єкт DateTimeImmutable, що представляє дату та час, вказані рядком у параметрі datetime, які були відформатовані у заданому форматі format

Список параметрів

format

Формат дати та часу у вигляді рядка (string), якому відповідає значення другого аргументу функції. Список варіантів форматування наведено нижче. Найчастіше, при форматуванні використовуються самі символи, як і функції date()

Усі поля ініціалізуються з поточною датою/часом. У більшості випадків необхідно їх "обнулити" (епоха Unix, 1970-01-01 00:00:00 UTC). Для цього потрібно додати символ ! як перший символ параметра formatили в качестве последнего. Для получения дополнительной информации смотрите документацию по каждому символу ниже.

Формат розбирається ліворуч, це означає, що в деяких ситуаціях порядок присутності символів формату впливає на результат. В разі z (День року) потрібно, щоб рік уже був розібраний, наприклад, за допомогою символів Yилиy

Символи для аналізу чисел допускають широкий діапазон значень, що виходить за межі логічного діапазону. Наприклад, d(день месяца) принимает значения в диапазоне от00до99. Єдиним обмеженням є кількість цифр. Коли задаються значення, що виходять за межі діапазону, спрацьовує механізм переповнення аналізатора дати/часу. Нижче показано кілька прикладів такої поведінки.

Це означає, що розібрані дані для літери формату є жадібними і зчитуватимуться до кількості цифр, що допускається форматом. Також це означає, що у рядку datetime не вистачає символів для наступних символів формату. Приклад на цій сторінці також ілюструє проблему.

Список можливих символів для складання рядка format

Символ в строке `format`	Опис	Возможные значения
День	---	---
`d`и`j`	День місяця, 2 цифри з нулем на початку чи без нього	Від `01`до`31` або від до`31`. . (допускається використання двозначних чисел, що перевищують кількість днів на місяці, у цьому випадку різниця переноситься на наступний місяць. Наприклад, використання числа 33 із січнем означає 2 лютого)
`D`и`l`	Текстова вистава дня тижня	Від `Mon`до`Sun` або від `Sunday`до`Saturday`. . Якщо задане ім'я дня відрізняється від імені дня, що належить розібраній даті (або за замовчуванням), то відбувається переповнення до наступною дати із заданим ім'ям дня. Дивіться нижче приклади для пояснення.
`S`	Суфікс для числа в англійській нумерації, 2 літери. Ці літери будуть пропущені при розборі рядка.	`stndrd`или`th`
`z`	Номер з початку року (починаючи з 0); має передувати `Y`или`y`	C по`365`. . (Допускаються тризначні числа, що перевищують числа на рік, у цьому випадку різниця переноситься на наступний рік. Наприклад, використання числа 366 з 2022 роком означає 2 січня 2023 року)
Місяць	---	---
`F`и`M`	Текстова вистава місяця, наприклад January або Sept	С`January`по`December` або з `Jan`по`Dec`
`m`и`n`	Числове уявлення місяця з першим нулем або без нього	С`01`по`12` або з по`12`. . (Допускаються двоцифрові числа більше 12, у цьому випадку різниця переноситься на наступний рік. Наприклад, використання числа 13 означає січень наступного року)
Рік	---	---
`X`и`x`	Повне числове подання року, до 19 цифр, з префіксом `+` или`-`	Приклади: `00557871999-2003+10191`
`Y`	Повне числове уявлення року, до 4 цифр.	Приклади: `005578719992003`
`y`	2 цифри у поданні року (в діапазоні 1970-2069 включно)	Приклади: `99`или`03` (буде розшифровано як `1999`и`2003` відповідно)
Час	---	---
`a`и`A`	До полудня та Після полудня	`am`или`pm`
`g`и`h`	12-ти годинний формат часу з першим нулем або без нього	С по`12` або з `01`по`12`. . (Допускається використання двозначних чисел більше 12, у цьому випадку різниця переноситься на наступний день. Наприклад, використання числа `14` означає `02` у наступному періоді AM/PM)
`G`и`H`	24-х годинний формат часу з нулем на початку або без нього	С по`23` або з `00`по`23` (Допускаються двоцифрові числа більше 24, у цьому випадку різниця переноситься на наступний день. Наприклад, використання `26` означає `02:00` наступного дня)
`i`	Хвилини з нулем на початку	С`00`по`59`. . (допускається використання двозначних чисел більше 59, у цьому випадку різниця переноситься на наступну годину. Наприклад, використання числа `66` означає `:06` наступної години)
`s`	Секунди з нулем на початку	Від `00`до`59`. . (Допускаються двоцифрові числа більше 59, у цьому випадку різниця переноситься на наступну хвилину. Наприклад, використання числа `90` означає `:30` наступної хвилини)
`v`	Дріб у мілісекундах (до 3 цифр)	Приклади: `120.12` секунд), `3450.345` секунд)
`u`	Дріб у мікросекундах (до 6 цифр)	Приклади: `450.45` секунд), `6543210.654321` секунд)
Часовий пояс	---	---
`eOP`и`T`	Ідентифікатор часового поясу, або різниця в годиннику щодо UTC, або різниця щодо UTC з двокрапкою між годинником і хвилинами, або абревіатура часового поясу	Приклади: `UTCGMTAtlantic/Azores`или`+0200`или`+02:00`или`ESTMDT`
Дата/Час повністю	---	---
`U`	Кількість секунд від початку Епохи Unix (January 1 1970 00:00:00 GMT)	Приклад: `1292177455`
Пробіл та Розділювачі	---	---
(пробіл)	Нуль або кілька символів пробілу, табуляції, нерозривної пробілу NBSP (U+A0) або вузької нерозривної пробілу NNBSP (U+202F)	Приклад: `"\t"" "`
`#`	Один із наступних символів: `:,-` или`) .`	Приклад:
`:,-` или`) .`	Розділювач символ.	Приклад: `-`
`?`	Один випадковий (будь-який) символ	Приклад: `^` (Будьте уважні: у UTF-8 кодуванні вам може знадобитися більше одного `?` тому що там один символ може займати більше одного байта. У таких випадках може допомогти використання `*`
`*`	Будь-яка кількість будь-яких символів до наступного роздільника	Приклад: ``в`Y--d` для рядка `2009-aWord-08` буде відповідати `aWord`
`!`	Скидає всі поля (рік, місяць, день, година, хвилина, секунда та часовий пояс) до нульових значень ( для години, хвилини, секунди, для місяця та дня, `1970` для року та `UTC` для інформації про часовий пояс).	Без `!` всі поля відповідатимуть поточному часу.
`	`	Скидає значення незаданих полів (рік, місяць, день, година, хвилина, секунда, часовий пояс) до нульових значень.
`+`	Якщо заданий цей специфікатор, дані, що завершують рядок (нуль байт наприклад) не викликатимуть помилку, тільки попередження	ИспользуйтеDateTime::getLastErrors() для визначення, чи були у рядку завершальні символи.

Наявність у рядку формату символів, що не розпізнаються, відсутніх у списку вище, призведе до помилки розбору рядка. У цьому випадку повідомлення про помилку буде додано до структури, що повертається. Отримати це повідомлення можна за допомогою функції DateTime::getLastErrors()

Для вставки вformat літерний символ, ви повинні екранувати його за допомогою зворотного слєша(\

Якщо format не містить символ !, то значення полів, не заданих у рядку формату, будуть встановлені відповідно до поточного часу.

Якщо format містить символ !, то значення полів, не заданих у рядку формату (як і значення полів зліва від !) будуть встановлені відповідно до значень полів початку Епохи Unix.

Якщо будь-який символ часу розібраний, всі інші поля, пов'язані з часом, встановлюються в "0", якщо вони також не розібрані.

Початок епохи Unix 1970-01-01 00:00:00 UTC.

datetime

Рядок, що представляє час.

timezone

Об'єкт класу DateTimeZone, що представляє очікуваний часовий пояс.

Якщо timezoneне указан или**null**иdatetime не містить часовий пояс, то буде використано поточний часовий пояс.

Зауваження :

Параметрtimezone і поточний часовий пояс буде проігноровано, якщо параметр datetime також містить мітку часу UNIX (тобто timestamp виду 946684800) або зазначений часовий пояс (тобто 2010-01-28T15:00:00+02:00

Значення, що повертаються

Повертає новий екземпляр DateTimeImmutable або **false**в случае возникновения ошибки.

Помилки

Функція викидає ValueError, якщо параметр datetime містить нульові байти.

список змін

Версия	Опис
8.2.9	Специфікатор (пробіл) також підтримує символи нерозривної пробілу NBSP (U+A0) і вузької нерозривної пробілу NNBSP (U+202F).
8.2.0	Додані специфікатори `X`и`x`параметру`format`
8.0.21, 8.1.8, 8.2.0	Тепер, коли у параметр `datetime` передаються нульові байти, викидається виняток ValueError, Раніше така ситуація ігнорувалась.
7.3.0	Доданий специфікатор `v`параметру`format`

Приклади

Приклад #1 Приклад використання DateTimeImmutable::createFromFormat()****

Об'єктно-орієнтований стиль

Loading...

Приклад #2 Використання певних констант формату за допомогою DateTimeImmutable::createFromFormat()

Об'єктно-орієнтований стиль

Loading...

Константи форматування, що використовуються в даному прикладі, складаються з рядка символів для форматування об'єкта DateTimeImmutable. У більшості випадків ці літери збігаються з тими самими елементами інформації про дату/час, які визначені в параметрах вище, але вони, як правило, більш м'які.

Приклад #3 Тонкощі DateTimeImmutable::createFromFormat()

Loading...

Висновок наведеного прикладу буде схожим на:

Текущее время: 2022-06-02 15:50:46
Формат: Y-m-d; 2009-02-15 15:50:46
Формат: Y-m-d H:i:s; 2009-02-15 15:16:17
Формат: Y-m-!d H:i:s; 1970-01-15 15:16:17
Формат: !d; 1970-01-15 00:00:00
Формат: i; 2022-06-02 00:15:00

Приклад #4 Форматування рядка за допомогою літеральних символів

Loading...

Висновок наведеного прикладу буде схожим на:

23:15:03

Приклад #5 Поведінка при переповненні

Loading...

Висновок наведеного прикладу буде схожим на:

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

Хоча результат виглядає дивно, він правильний, тому що трапляються такі переповнення:

97секунд перевалюють за хвилину, залишаючи37секунд.
61хвилин перевалює за годину, залишаючи хвилину.
35днів перевалюють за місяць, залишаючи 4дня. Кількість днів залежить від місяця, тому що не в кожному місяці однакова кількість днів.
18місяців перевалюють за рік, залишаючи6місяців.

Приклад #6 Поведінка імені переповненого дня

Loading...

Висновок наведеного прикладу буде схожим на:

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

Хоча результат виглядає дивно, він правильний, тому що трапляються такі переповнення:

3 Aug 2020 25:00:00перевалює за(Tue) 4 Aug 2020 01:00
ЗастосовуєтьсяMon, що перекладає дату наMon, 10 Aug 2020 01:00:00. Пояснення щодо ключових слів, таких якMon, описано у розділі відносні формати.

Для виявлення переповнень у датах можна використовувати метод DateTimeImmutable::getLastErrors(), який включатиме попередження, якщо відбулося переповнення.

Приклад #7 Виявлення переповнення дат

Loading...

Висновок наведеного прикладу буде схожим на:

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

Приклад #8 Жадібна поведінка при розборі

Loading...

Висновок наведеного прикладу буде схожим на:

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

ФорматG призначений для розбору 24-годинного годинника з провідним нулем або без нього. Для цього необхідно розібрати 1 чи 2 цифри. Так як є дві наступні цифри, він жадібно зчитує це як 60

Наступні символи формату iиs вимагають двох цифр. Це означає, що 10 передається як хвилина (i) і що потім залишається недостатньо цифр для розбору секунд (s

На цю проблему вказує масив errors

Крім того, година 60находится вне диапазона -24, что добавляет предупреждение в массивwarnings про те, що час є недійсним.

Дивіться також

DateTimeImmutable::__construct() - Повертає новий об'єкт DateTimeImmutable
DateTimeImmutable::getLastErrors() - Повертає попередження та помилки
checkdate() - Перевіряє коректність дати за григоріанським календарем
strptime() - Розбирає рядок дати/часу, згенерований функцією strftime