Как избежать проблем с неработающими шорткодами в WordPress

Диагностика проблемы с неработающими шорткодами

Часто при добавлении шорткодов в записи или страницы WordPress пользователи видят не результат работы шорткода, а сам текст вида [my_shortcode]. Это значит, что WordPress не обработал шорткод. Основные причины:

• Шорткод не зарегистрирован в теме или плагине;
• Код регистрации шорткода содержит ошибки;
• Шорткод используется в текстовом редакторе, где не разрешено выполнение шорткодов (например, в виджетах без поддержки);
• Конфликты с другими плагинами или темой;
• Использование шорткода в местах, где контент фильтры WordPress не применяются.

Шаги по устранению проблем с шорткодами

1. Проверка регистрации шорткода

Убедитесь, что шорткод зарегистрирован правильно в functions.php вашей темы или в плагине. Пример корректной регистрации:

function wpweb_custom_shortcode() {
    return '<div>Пример вывода шорткода</div>';
}
add_shortcode('my_shortcode', 'wpweb_custom_shortcode');

Обратите внимание, что функция должна возвращать строку, а не выводить ее напрямую.

2. Использование шорткода в правильных местах

В редакторе Gutenberg или Classic Editor шорткоды работают по умолчанию. Если вы хотите использовать шорткод в виджете, убедитесь, что в функции functions.php есть поддержка:

add_filter('widget_text', 'do_shortcode');

Без этого шорткод в текстовом виджете не будет обработан.

3. Проверка конфликтов с плагинами и темой

Отключите все плагины кроме того, где зарегистрирован шорткод, и смените тему на стандартную (например, Twenty Twenty-Three). Если шорткод заработал, включайте по одному плагину, чтобы найти конфликт.

4. Использование шорткодов в PHP шаблонах

Для вывода шорткода прямо в PHP-шаблонах используйте функцию do_shortcode():

echo do_shortcode('[my_shortcode]');

Без вызова do_shortcode() шорткод не обработается.

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

После исправлений:

• Очистите кэш браузера и кэш плагинов кэширования.
• Откройте страницу или запись с шорткодом — он должен отображаться как HTML, а не как текст.
• В PHP-шаблоне проверьте, что вызов do_shortcode() выводит ожидаемый результат.

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

• Возврат NULL или пустой строки из функции шорткода — шорткод ничего не выводит. Проверьте, что функция возвращает строку, а не выводит через echo.
• Отсутствие регистрации шорткода — шорткод выводится как текст. Проверьте, что add_shortcode() вызывается в нужном файле и подключается при загрузке сайта.
• Использование шорткода в виджете без фильтра do_shortcode — добавьте add_filter('widget_text', 'do_shortcode'); в functions.php.
• Использование шорткода в местах без поддержки фильтров — используйте do_shortcode() в PHP, либо не вставляйте шорткод в эти места.

Практические советы по безопасности и производительности

• Не включайте в шорткод тяжелые запросы к базе или внешние API без кэширования — это замедлит загрузку страницы.
• Используйте wp_cache или transient API для кеширования результата шорткода, если он сложный.
• Не выводите пользовательский ввод напрямую — используйте функции экранирования (esc_html(), esc_url() и др.) внутри шорткода.
• Для сложных шорткодов лучше создавать отдельные плагины, а не хранить код в functions.php.

Сравнение вариантов реализации шорткода