🛠 Как добавить свой шорткод в WordPress: разбор add_shortcode() [+2 примера]

Создали сниппет, добавили в functions.php, а WordPress говорит «cheatin' uh?» Знакомо? Шорткоды, базовый механизм расширения WordPress, и add_shortcode() открывает его за 15 строк кода. Но между «Hello World» и реальным сценарием есть подводные камни: return против echo, порядок параметров callback-функции, конфликт тегов.

Шорткоды появились ещё в WordPress 2.5 и с тех пор стали основой экосистемы: контактные формы, галереи, слайдеры, вывод кастомных полей, всё это живёт внутри квадратных скобок. add_shortcode() не менялась годами, и освоить её можно за полчаса.

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

💡 Быстрый обзор:

• Синтаксис и параметры add_shortcode(), тег и callback
• Правило: всегда return, никогда echo
• Хук init, почему без него шорткод может не работать
• Два способа передать данные: контент между тегами и атрибуты
• Готовый код: шорткод для автогода и списка пользователей

Как работает add_shortcode() в WordPress

Функция add_shortcode(), точка входа для регистрации любого кастомного шорткода. Она принимает два обязательных параметра: уникальный тег и имя callback-функции, которая вернёт контент.

Согласно документации WordPress, callback получает три аргумента в фиксированном порядке:

• $attributes, массив атрибутов, переданных в шорткоде
• $content, текст между открывающим и закрывающим тегом
• $tag, имя тега, с которым шорткод зарегистрирован

Базовый пример, шорткод, который выводит «Hello World!»:

1
// Callback-функция шорткода
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Регистрация шорткода
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Код добавляется в functions.php дочерней темы или через плагин Code Snippets. После этого [hello-world] в редакторе поста выведет «Hello World!».

Почему return, а не echo

Обратите внимание на return внутри callback-функции. Если использовать echo, вывод случится до того, как WordPress построит остальную страницу, «Hello World!» окажется в самом верху, а контент вокруг съедет.

Правило простое: **callback шорткода всегда возвращает значение через ****return**. Никаких echo, print или прямого вывода HTML вне буфера.

Хук init обязателен

Разработчики на WordPress.org рекомендуют вешать регистрацию шорткода на хук init, а не вызывать add_shortcode() напрямую в теле functions.php. Без init WordPress может не успеть инициализировать внутренние механизмы, и шорткод просто не сработает.

Синтаксис и параметры

Сигнатура функции:

1
add_shortcode( string $tag, callable $callback )

$tag, имя шорткода (без скобок). Если два плагина регистрируют шорткод с одинаковым тегом, последний переопределит предыдущий. Чтобы избежать конфликтов, добавляйте уникальный префикс: не [gallery], а [myplugin_gallery].

$callback, имя функции, которая возвращает контент. Можно передать строку с названием функции, анонимную функцию или метод класса (передав массив [ $object, 'method_name' ]).

Как использовать шорткоды в редакторе

В редакторе WordPress, Gutenberg или Classic, шорткод вставляется в квадратных скобках. Для нашего примера:

[hello-world]

Полная форма с закрывающим тегом тоже работает:

[hello-world][/hello-world]

Второй вариант нужен, когда между тегами передаётся контент (об этом ниже).

Как вызвать шорткод в PHP

В шаблонах темы или плагинах шорткоды запускаются через do_shortcode():

1
echo do_shortcode( '[hello-world]' );

Функция принимает строку с шорткодом и возвращает результат его выполнения. Полезна, когда нужно встроить вывод шорткода в PHP-логику, например, в header.php или внутри цикла.

Передача данных в шорткод: два способа

Способ 1: контент между тегами

Заключите данные между открывающим и закрывающим тегом:

[hello-world]from John to Mary[/hello-world]

Callback получает строку from John to Mary через второй параметр $content:

1
// Callback с подстановкой контента между тегами
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Регистрация
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Результат: «Hello from John to Mary World!».

Способ 2: атрибуты

Передайте параметры прямо в открывающем теге:

[hello-world from="John" to="Mary"][/hello-world]

В callback-функции атрибуты доступны через первый параметр $attributes, ассоциативный массив, где ключи совпадают с названиями атрибутов:

1
// Callback с чтением атрибутов шорткода
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Регистрация
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Вывод: «Hello from John to Mary!». Атрибуты удобнее для структурированных данных (цена, URL, ID), а контент между тегами, для произвольного текста.

На практике к атрибутам стоит сразу добавить shortcode_atts(), встроенную функцию WordPress, которая сливает переданные атрибуты с массивом значений по умолчанию. Без неё обращение к $attributes['from'] выбросит PHP Notice, если пользователь не указал атрибут. С shortcode_atts() вы всегда получаете заполненный массив: заданные ключи с fallback-значениями, а неизвестные атрибуты фильтруются автоматически.

Два готовых шорткода для WordPress

1. Автоматический текущий год

Шорткод [current-year], который сам подставляет актуальный год, не нужно править дату в футере каждый январь:

1
// Callback: возвращает текущий год через date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Регистрация шорткода [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Разместите [current-year] в футере или тексте поста, и год будет обновляться автоматически.

2. Список зарегистрированных пользователей

Шорткод [users-list] выводит имена всех пользователей сайта маркированным списком. Пригодится на странице «Команда» или в админ-отчётах:

1
// Callback: получает всех пользователей и формирует HTML-список
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Регистрация шорткода [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() без аргументов возвращает всех пользователей. Чтобы ограничить выборку ролью, передайте массив: get_users( [ 'role' => 'editor' ] ). Код добавляется в functions.php активной темы или в кастомный плагин.

Видео: создание шорткодов в WordPress

Короткое видео по теме, регистрация шорткода с нуля, от написания функции до тестирования в редакторе:

⁉️🤔 Частые вопросы

Что будет, если два плагина зарегистрируют шорткод с одинаковым тегом?

WordPress выполнит тот, который загрузился последним. Первый шорткод будет переопределён, молча, без ошибок. Поэтому в своих шорткодах всегда используйте префикс: [acme_gallery] вместо [gallery]. Так вы исключаете конфликт с любым другим плагином или темой.

Можно ли вызывать шорткоды внутри других шорткодов?

Да. Если callback первого шорткода возвращает строку с тегом второго, WordPress обработает вложенный шорткод автоматически. Но не забывайте про do_shortcode(): если вы формируете контент вручную и в нём есть шорткоды, пропустите строку через do_shortcode() явно. Стандартное поведение the_content делает это самостоятельно, а прямой вызов callback-функции, нет.

Где размещать код шорткодов, в теме или в плагине?

Кастомные шорткоды несут функциональность, а не внешний вид, поэтому правильнее вынести их в отдельный плагин. Смена темы не сломает сайт: шорткоды продолжат работать. Минимум, дочерняя тема, если вы точно не планируете менять основную.

Есть ли ограничения на имя тега?

Имя должно состоять из латинских букв, цифр и дефисов. Пробелы, подчёркивания и спецсимволы не допускаются. Рекомендуемая длина, до 20 символов, нижний регистр. Пример: [my-plugin-shortcode].

Как отлаживать шорткод, если он ничего не выводит?

Первый шаг, включите WP_DEBUG в wp-config.php. Второй, проверьте, что callback возвращает значение через return, а не echo. Третий, убедитесь, что хук init присутствует. Если ошибок нет, но вывод пустой, добавьте error_log() в callback и смотрите логи сервера.

Что нужно запомнить о шорткодах WordPress

Шорткоды, зрелый и стабильный механизм. add_shortcode() не менялась годами: тег, callback, хук init, return вместо echo. Запомните эти четыре вещи, и любой кастомный шорткод заработает с первого раза.

• Если выводите год в футере, берите готовый [current-year].
• Если нужен список пользователей, [users-list] с фильтром по роли.
• Если пишете свой шорткод с нуля, всегда префикс и всегда init.

Для следующего шага посмотрите, как оформить шорткод в отдельный плагин и выложить в каталог WordPress.org — это лучший способ отделить функциональность от темы и прокачать профиль разработчика.