Как использовать функцию wp_unique_slug для решения проблем с URL в WordPress

Что такое wp_unique_slug и зачем она нужна

В WordPress wp_unique_slug — это внутренняя функция, которая отвечает за генерацию уникальных слагов (URL-идентификаторов) для записей, страниц, таксономий и других типов контента. Она предотвращает конфликты, когда пытаются создать две записи с одинаковым слагом, автоматически добавляя суффикс с числом.

Часто разработчики сталкиваются с проблемой дубликатов URL или некорректного формирования слагов при программном создании записей или кастомных типах постов. Правильное использование wp_unique_slug помогает избежать ошибок, связанных с конфликтами URL и 404 ошибками.

Диагностика проблем с URL и слагами в WordPress

Типичные признаки проблем с слагами:

• При программном создании записи с заданным слагом WordPress не меняет его, и появляется конфликт с существующим URL.
• Новые записи с одинаковым слагом перезаписывают старые или ведут на 404.
• Проблемы с таксономиями, когда слаги повторяются и вызывают ошибки маршрутизации.

Для диагностики проверьте:

• В базе данных wp_posts.post_name — есть ли дубли с одинаковыми значениями.
• Логи ошибок сервера на предмет конфликтов rewrite-правил.
• Правильность кода, который создаёт или обновляет записи — вызывается ли wp_unique_slug перед сохранением.

Пошаговое решение: правильное использование wp_unique_slug при создании записи

Рассмотрим пример создания записи с уникальным слагом на PHP в файле темы или плагина.

function create_post_with_unique_slug($title, $content, $desired_slug) {
    // Проверяем, что слаг уникален
    $unique_slug = wp_unique_slug(
        $desired_slug, // желаемый слаг
        0,            // ID записи, если обновляем. 0 — новая запись
        'post',       // тип записи
        '',           // родительская запись (для вложенных типов)
        ''            // объект для исключения
    );

    // Создаем массив данных для вставки записи
    $post_data = [
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'publish',
        'post_name'    => $unique_slug,
        'post_type'    => 'post',
    ];

    // Вставляем запись
    $post_id = wp_insert_post($post_data);

    if (is_wp_error($post_id)) {
        return $post_id; // Возвращаем ошибку
    }

    return $post_id;
}

Вызывая эту функцию, вы гарантируете, что слаг всегда будет уникальным, даже если $desired_slug уже занят.

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

$post_id = create_post_with_unique_slug('Заголовок', 'Содержимое записи', 'my-post-slug');
if (is_wp_error($post_id)) {
    error_log('Ошибка создания записи: ' . $post_id->get_error_message());
} else {
    echo 'Запись создана с ID ' . $post_id;
}

Проверка результата после внедрения

Чтобы убедиться, что слаги уникальны и проблема решена:

• Просмотрите таблицу wp_posts в базе данных, убедитесь, что в колонке post_name нет дубликатов.
• Создайте несколько записей с одинаковым желаемым слагом через ваш код — они должны получать уникальные суффиксы, например my-post-slug, my-post-slug-2, my-post-slug-3.
• Проверьте в админке WordPress и на сайте, что URL ведут на правильные записи без конфликтов.

Частые ошибки при работе с wp_unique_slug и как их исправить

• Не используете wp_unique_slug перед вставкой записи: приводит к слагам с дублирующимися значениями и конфликтам URL. Решение: всегда генерируйте уникальный слаг программно.
• Передаете неправильные параметры в wp_unique_slug: Например, пропускаете тип записи или ID родителя для вложенных типов. Это может приводить к неверной проверке уникальности. Решение: внимательно указывайте все параметры.
• Забываете обновить запись с новым слагом при ручном изменении: Если меняете слаг вручную, нужно убедиться, что он уникален, иначе WordPress не применит изменения. Используйте функцию для проверки перед обновлением.
• Конфликты с пользовательскими типами записей и таксономиями: При создании слагов для кастомных таксономий обязательно передавайте корректный тип объекта в wp_unique_slug, иначе уникальность не будет проверена корректно.

Практические советы по оптимизации и безопасности

• Используйте wp_unique_slug не только при создании, но и при массовом импорте контента — это избавит базу данных от конфликтов и ошибок 404.
• Для кастомных типов постов и таксономий всегда явно указывайте тип и родителя, чтобы избежать пересечений с другими типами.
• Избегайте прямого изменения слагов в базе данных без проверки уникальности — это может сломать маршрутизацию.
• При использовании REST API для создания записей интегрируйте вызов wp_unique_slug на серверной стороне, чтобы не полагаться на клиентское формирование слагов.
• Регулярно проверяйте таблицу wp_posts на предмет дубликатов с помощью SQL-запроса:

SELECT post_name, COUNT(*) c FROM wp_posts GROUP BY post_name HAVING c > 1;

Если есть результаты — это сигнал о проблемах с уникальностью слагов.

Сравнение вариантов решения проблемы с дублирующимися слагами