Преобразование даты с функцией MYSQL2DATE() в WordPress

# MYSQL2DATE() │ WP 0.71

Функция MYSQL2DATE() преобразует указанную дату (в виде строки) в другой формат. Формат указывается так же, как в стандартной функции PHP date().

### Ожидания

Предполагается, что дата передается в местном времени (не в UTC). 
Форматы 'U' и 'G' вернут число — сумму метки времени и смещения часового пояса сайта. Это необычное поведение! Оно возникло, когда дата могла передаваться в UTC для получения метки времени Unix. 

В отличие от функции PHP date(), эта функция переводит названия месяцев на текущий язык.

Функция работает на раннем этапе загрузки WordPress, даже до значения константы SHORTINIT.

### Использование

- **Функция:** wp_date()
- **Используется в:** 
  - get_post_modified_time()
  - get_comment_time()
  - get_comment_date()
  - get_the_date()
  - get_post_time()

### Время выполнения
- 1 раз — 0.00018 сек (быстро)
- 50000 раз — 4.42 сек (быстро)

### Возвращаемое значение

Функция может вернуть:
- число — если формат U или G.
- строку — в других случаях.
- false — в случае ошибки.

### Использование функции

```php
mysql2date($format, $date, $translate);

• $format (строка) (обязательно): Формат даты, который нужно получить. Например, j n Y вернет 25 12 2011. Примеры форматов можно посмотреть в документации WordPress.
• $date (строка) (обязательно): Дата, которую нужно преобразовать. Она может быть в любом общепринятом формате. Обычно дата передается в формате MySQL Y-m-d H:i:s.
• $translate (бол. true): Указывает, нужно ли переводить названия месяцев и дней на текущий язык в WordPress. По умолчанию: true.

Примеры

1. Простой пример работы функции

echo mysql2date('d.M.Y H:i', '2015-07-24 15:23:14'); // 24.Jul.2015 15:23
echo mysql2date('d-m-Y', '2020-10-25');              // 25-10-2020
echo mysql2date('F j, Y', '2023-06-22 10:30:00');    // June 22, 2023
echo mysql2date('l, F jS, Y at g:i A', '2023-06-22 10:30:00', false); // Thursday, June 22nd, 2023 at 10:30 AM

2. Получение даты публикации поста в формате D-M-Y

echo mysql2date('d-m-Y', $post->post_date); // 02-12-2011

3. Особенности форматов U и G

Форматы U и G работают одинаково:

echo mysql2date('U', '2012-02-23 06:12:45'); // 1329977565
echo mysql2date('G', '2012-02-23 06:12:45'); // 1329977565

Важно! При использовании форматов U и G переданная дата должна быть также в зоне UTC (GMT)!

Например, если передать дату публикации $post->post_date, то вы получите метку времени Unix с учетом смещения по часовому поясу сайта, вместо метки времени самой даты. Это сделано для совместимости с ранее написанным кодом.

Пример проверки:

// здесь мы используем текущее время в зоне UTC (GMT)
$time = mysql2date('U', gmdate('Y-m-d H:i:s'));
var_dump(time() === $time); // bool(true)

Из-за этой особенности не рекомендуется использовать mysql2date() для получения метки времени Unix, так как поведение может быть неочевидным.

Как правильно получить метку времени из даты (не в зоне UTC)

Можно использовать следующий код, который явно показывает, что происходит с датой:

$post_time = date_create($post->post_date, wp_timezone())->getTimestamp();

Здесь мы передаем дату поста в часовом поясе сайта (не UTC) и получаем метку времени Unix (как и ожидалось, в зоне UTC). Это происходит потому, что во втором параметре date_create() мы указываем часовой пояс, в котором передана дата.

Изменения

• С версии 0.71 добавлена функция.

Код функции MYSQL2DATE()

function mysql2date($format, $date, $translate = true) {
    if (empty($date)) {
        return false;
    }

    $timezone = wp_timezone();
    $datetime = date_create($date, $timezone);

    if (false === $datetime) {
        return false;
    }

    // Возвращает сумму метки времени с учетом смещения по часовому поясу. В идеале, не должно использоваться.
    if ('G' === $format || 'U' === $format) {
        return $datetime->getTimestamp() + $datetime->getOffset();
    }

    if ($translate) {
        return wp_date($format, $datetime->getTimestamp(), $timezone);
    }

    return $datetime->format($format);
}