Add_shortcode() у wordpress: повний розбір з прикладами

Q: Як налагоджувати шорткод, якщо він нічого не виводить?

Перший крок, увімкніть WP_DEBUG у wp-config.php. Другий, перевірте, що callback повертає значення через return, а не echo. Третій, переконайтеся, що хук init присутній. Якщо помилок немає, але виведення порожнє, додайте error_log() у callback і дивіться логи сервера.

Створили сніпет, додали в 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 — це найкращий спосіб відокремити функціональність від теми та прокачати профіль розробника.