Функция cot_date2stamp в Cotonti

Описание функции. Функция cot_date2stamp преобразует строковое представление даты в UNIX timestamp. Она поддерживает как стандартные форматы даты (например, MySQL-формат), так и пользовательские форматы, задаваемые через параметр $format.
Разбор и объяснение функции cot_date2stamp.

/**
 * Converts date into UNIX timestamp.
 * @param string $date Formatted date as a string.
 * @param string $format Format on which to base the conversion. Defaults to MySQL date format.
 * @see https://www.php.net/manual/en/datetimeimmutable.createfromformat.php for more information about format.
 *
 * @return int UNIX timestamp or NULL for 0000-00-00
 *
 * @todo use IntlDateFormatter::parse() for locale-dependent parsing
 * @see https://www.php.net/manual/en/intldateformatter.parse.php
 */
function cot_date2stamp($date, $format = null)
{
    if (
        empty($date)
        || in_array($date, ['0000-00-00', '0000-00-00 00:00:00', '0000-00-00 00:00'])
        || mb_strtolower($date) === 'null'
    ) {
        return null;
    }

    if (!$format || $format == 'auto') {
        $result = strtotime($date);
        return ($result === false) ? null : $result;
    }

    // for locale-independent parsing
    $dateTime = date_parse_from_format($format, $date);

    return mktime(
        (int) $dateTime['hour'],
        (int) $dateTime['minute'],
        (int) $dateTime['second'],
        (int) $dateTime['month'],
        (int) $dateTime['day'],
        (int) $dateTime['year']
    );
}

Параметры функции
$date (string):

Обязательный параметр.
Строка, представляющая дату, которую нужно преобразовать.
$format (string|null):

Опциональный параметр.
Определяет формат даты, на основе которого будет выполнено преобразование. Если не указан (или равен null), используется автоопределение формата через strtotime.
Возвращаемое значение
Возвращает UNIX timestamp (целое число).
Если дата некорректна или представлена в виде 0000-00-00 (и подобных значений), возвращает null.
Подробное объяснение условий и действий внутри функции

1. Проверка некорректных значений даты:

if (
    empty($date)
    || in_array($date, ['0000-00-00', '0000-00-00 00:00:00', '0000-00-00 00:00'])
    || mb_strtolower($date) === 'null'
) {
    return null;
}

Объяснение:

Если дата пуста (empty($date)).
Если дата равна одному из стандартных "пустых" значений (0000-00-00, 0000-00-00 00:00:00 и т.д.).
Если дата явно задана строкой 'null'.
Функция немедленно возвращает null, так как такие значения не могут быть преобразованы в корректный timestamp.

2. Автоматическое определение формата даты:

if (!$format || $format == 'auto') {
    $result = strtotime($date);
    return ($result === false) ? null : $result;
}

Объяснение:

Если формат не указан (null) или задан явно как 'auto', используется функция strtotime для автоматического анализа строки даты.
Если strtotime возвращает false (например, если формат даты некорректен), возвращается null.

3. Локально-независимое преобразование:

$dateTime = date_parse_from_format($format, $date);

Объяснение:

Если формат указан, используется функция date_parse_from_format, которая позволяет разобрать дату в соответствии с заданным форматом.
Результат будет представлен в виде массива с ключами (hour, minute, second, month, day, year), которые используются для построения timestamp.

4. Создание UNIX timestamp:

return mktime(
    (int) $dateTime['hour'],
    (int) $dateTime['minute'],
    (int) $dateTime['second'],
    (int) $dateTime['month'],
    (int) $dateTime['day'],
    (int) $dateTime['year']
);

Объяснение:

Используется функция mktime для создания UNIX timestamp из разобранных компонентов даты:
Часы (hour), минуты (minute), секунды (second).
Месяц (month), день (day), год (year).
Если какие-либо ключи массива $dateTime отсутствуют или некорректны, они интерпретируются как 0, что может привести к созданию некорректной даты.

Назначение функции
cot_date2stamp позволяет легко преобразовать даты из различных форматов в UNIX timestamp, что особенно важно для работы с базами данных, пользовательским вводом или различными региональными настройками.

Применение в Cotonti
Преобразование пользовательского ввода:

Если пользователи вводят даты в разных форматах, функция помогает их унифицировать.
Работа с базами данных:

MySQL хранит даты в формате YYYY-MM-DD HH:MM:SS. cot_date2stamp конвертирует такие строки в timestamp для дальнейших вычислений.

Локализованные форматы:

С помощью параметра $format можно обрабатывать даты, указанные в региональных форматах, что важно для мультиязычных приложений.

Рекомендации по использованию

Явно указывайте формат:

Если формат данных заранее известен, лучше явно передавать его через параметр $format вместо использования автоопределения (strtotime), чтобы избежать ошибок.

Проверяйте результат:

Всегда проверяйте возвращаемое значение на null, чтобы избежать некорректной работы с пустыми или некорректными датами.

Используйте для совместимости:

Функция удобна для приведения дат к единому формату в системах, где даты могут поступать из разных источников.

Пример использовани функции cot_date2stamp в Cotonti

'USERS_PROFILE_BIRTHDATE' => cot_selectbox_date(cot_date2stamp($urr['user_birthdate']), 'short', 'ruserbirthdate', cot_date('Y', Cot::$sys['now']), cot_date('Y', Cot::$sys['now']) - 100, false),

Давайте разберем выражение детально:

'USERS_PROFILE_BIRTHDATE' => cot_selectbox_date(
    cot_date2stamp($urr['user_birthdate']),
    'short',
    'ruserbirthdate',
    cot_date('Y', Cot::$sys['now']),
    cot_date('Y', Cot::$sys['now']) - 100,
    false
),

 

Контекст
Эта строка задает массив, где ключ 'USERS_PROFILE_BIRTHDATE' указывает на HTML-элемент (в данном случае, выпадающий список даты), который генерируется с помощью функции cot_selectbox_date.

Аргументы функции cot_selectbox_date
Функция cot_selectbox_date используется для создания выпадающего списка выбора даты. Она принимает следующие параметры:

cot_date2stamp($urr['user_birthdate']):

Преобразует дату рождения пользователя (хранящуюся в массиве $urr под ключом 'user_birthdate') в UNIX timestamp с помощью функции cot_date2stamp.
'short':

Формат отображения даты. 'short' обычно означает отображение только дня, месяца и года (без времени).
'ruserbirthdate':

Имя HTML-элемента. Этот идентификатор будет использован для привязки данных формы.

cot_date('Y', Cot::$sys['now']):

Текущий год, вычисленный с помощью функции cot_date. Используется в качестве верхней границы выбора года.
cot_date('Y', Cot::$sys['now']) - 100:

Год, равный текущему году минус 100 лет. Используется в качестве нижней границы выбора года. Таким образом, пользователь может выбрать дату рождения в пределах последних 100 лет.
false:

Опция, указывающая, требуется ли функция JavaScript или нет. В данном случае, false означает, что JS не будет добавлен.
Пошаговое объяснение
Получение даты рождения:

$urr['user_birthdate'] содержит дату рождения пользователя в виде строки (например, '2000-01-01').
Функция cot_date2stamp преобразует эту строку в UNIX timestamp для работы с функцией cot_selectbox_date.

Формирование диапазона выбора годов:

cot_date('Y', Cot::$sys['now']) вычисляет текущий год (например, 2025).
cot_date('Y', Cot::$sys['now']) - 100 задает нижнюю границу диапазона выбора (например, 1925).

Таким образом, пользователь может выбирать год рождения в пределах от 1925 до 2025 года.

Создание HTML-элемента:

Функция cot_selectbox_date генерирует HTML-код для выпадающего списка (или набора списков), в котором можно выбрать день, месяц и год.

Присвоение значения:

Список по умолчанию будет установлен на дату рождения пользователя, если она указана в $urr['user_birthdate'].

Пример результата
Если $urr['user_birthdate'] = '1990-05-15', то:

cot_date2stamp($urr['user_birthdate']) вернет UNIX timestamp для даты 15 мая 1990 года.
Выпадающий список будет содержать года с 1925 по 2025, а значение по умолчанию будет установлено на 1990.

Применение
Этот код используется в формах редактирования профиля пользователя, чтобы предоставить возможность выбора даты рождения. Он:

Удобен для обработки данных с ограничением диапазона (например, даты рождения).
Автоматически устанавливает текущую дату рождения пользователя, если она известна.