gmmktime()

Что такое функция gmmktime() в PHP?

Функция gmmktime() в PHP строит Unix-метку времени из отдельных компонентов даты и времени (час, минута, секунда, месяц, день, год), интерпретируя их как GMT/UTC, а не как локальный часовой пояс сервера. Unix-метка времени — это просто количество секунд, прошедших с 1 января 1970 года, 00:00:00 UTC, — значение, которое большинство функций PHP для работы с датами используют внутри.

На этой странице рассматриваются синтаксис и параметры функции, её отличие от mktime(), поведение при выходе значений за пределы допустимого диапазона, а также главный подводный камень: в современных версиях PHP параметры не являются полностью необязательными.

Название расшифровывается как greenwich mean time + make time.

Синтаксис

gmmktime(
    int $hour = current,
    ?int $minute = current,
    ?int $second = current,
    ?int $month = current,
    ?int $day = current,
    ?int $year = current
): int|false

Функция возвращает метку времени в виде целого числа или false, если аргументы задают недопустимое время.

Параметры

Важно: В PHP 8.0 и выше вызов gmmktime() без аргументов выбрасывает ArgumentCountError — параметр hour является обязательным. Любой пропущенный аргумент по умолчанию принимает соответствующее значение текущего времени GMT. Чтобы получить метку времени для «прямо сейчас», используйте time().

Базовый пример

Этот код генерирует Unix-метку времени для 3 марта 2023 года, 12:30:00 по GMT. Чтобы вывести её в удобочитаемом виде, используйте gmdate():

<?php

$timestamp = gmmktime(12, 30, 0, 3, 3, 2023);
echo gmdate('Y-m-d H:i:s', $timestamp);
// 2023-03-03 12:30:00

gmmktime() и mktime()

gmmktime() и mktime() принимают одинаковые аргументы и возвращают Unix-метку времени — единственное отличие состоит в том, в каком часовом поясе интерпретируются компоненты. gmmktime() трактует их как GMT/UTC, а mktime() — как локальный часовой пояс сервера. При одинаковых входных данных они возвращают разные метки времени, если местное время отличается от UTC:

<?php

date_default_timezone_set('America/New_York'); // UTC-4 in June

echo gmmktime(12, 0, 0, 6, 15, 2023), "\n"; // 1686830400  (12:00 UTC)
echo mktime(12, 0, 0, 6, 15, 2023), "\n";    // 1686844800  (12:00 New York = 16:00 UTC)

Используйте gmmktime(), когда ваши входные данные уже в UTC (метки времени из API, база данных, хранящаяся в UTC и т. д.), чтобы результат не зависел от настройки часового пояса сервера.

Выход значений за пределы диапазона

Компоненты не обязаны находиться в допустимых диапазонах. gmmktime() нормализует их, что удобно для арифметики с датами без ручного переноса:

<?php

// Month 13 rolls into the next year
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 13, 1, 2023)), "\n"; // 2024-01-01

// Day 32 of January becomes February 1st
echo gmdate('Y-m-d', gmmktime(0, 0, 0, 1, 32, 2023)), "\n"; // 2023-02-01

// Hour 25 rolls into the next day at 01:00
echo gmdate('Y-m-d H:i', gmmktime(25, 0, 0, 1, 1, 2023)), "\n"; // 2023-01-02 01:00

Это позволяет выражениям вида gmmktime(0, 0, 0, $month, $day + 7, $year) («семь дней спустя») корректно работать на границах месяцев и лет.

Когда использовать gmmktime()

• Единообразие часовых поясов. Поскольку функция всегда использует UTC, одни и те же аргументы дают одну и ту же метку времени на любом сервере, независимо от date.timezone.
• Построение метки времени из компонентов. Когда у вас есть отдельные значения часа/дня/месяца (например, из формы или разобранной строки), а не единая строка с датой. Для полной строки вида "2023-03-03 12:30" лучше обратиться к strtotime().
• Арифметика с датами через нормализацию. Прибавляйте или вычитайте из компонента и позвольте функции нормализовать результат.

Если нужно лишь проверить, что комбинация месяца/дня/года является реальной календарной датой, см. checkdate().

Заключение

gmmktime() преобразует отдельные компоненты даты и времени в Unix-метку времени на основе UTC. Её ключевые преимущества — независимость от часового пояса и автоматическая нормализация значений, выходящих за допустимые пределы. Помните, что в отличие от старых версий PHP, PHP 8+ требует как минимум аргумент hour; используйте mktime(), когда входные данные задаются в локальном времени, и gmdate() для форматирования результата.

Практика