Як створити шорткод wordpress: повний гайд за 10 хвилин

Q: Чому мій шорткод не працює, відображається як текст у квадратних дужках?

Три часті причини. Перша: add_shortcode викликано до хука init, перенесіть реєстрацію всередину add_action('init', ...). Друга: одрук в імені тега: [my_shortcode] у редакторі, а зареєстровано myshortcode. Третя: callback-функція використовує echo замість return, виведення потрапляє на початок сторінки, а на місці шорткоду порожньо. Найчастіше винен echo замість return у callback-функції. WordPress викликає обробники шорткодів до виведення основного контенту, результат echo потрапляє в буфер виведення раніше, ніж заголовок сторінки. Відкрийте вихідний код сторінки (Ctrl+U): якщо бачите HTML шорткоду на самому верху, до , проблема саме в цьому.

Q: Скільки шорткодів можна зареєструвати на одному сайті?

Технічного ліміту немає: $shortcode_tags — це звичайний PHP-масив, ви впретеся в пам’ять сервера значно пізніше, ніж у здоровий глузд. На практиці після 15-20 кастомних шорткодів варто замислитися: чи не час частину з них перенести в блоки Gutenberg? Шорткоди з унікальною логікою (email-обфускація, умовне виведення за роллю) залишайте. Шорткоди заради стилізації тексту ([highlight]) краще зробити стилем блоку або CSS-класом. Технічно, скільки завгодно, масив $shortcode_tags не має штучного ліміту. Практично, більше 20-25 шорткодів на одному сайті свідчить про те, що частину логіки час переносити в блоки. Кожен шорткод додає накладні витрати на парсинг контенту: перед виведенням WordPress проходить по всьому масиву зареєстрованих тегів і шукає збіги в тексті посту.

Потрібно вивести дату останнього оновлення посту в підвалі кожної статті. Або вставити форму підписки рівно посередині тексту, без редактора коду й танців із шаблонами. У WordPress для цього є шорткоди.

Шорткод — це короткий тег у квадратних дужках: [myshortcode]. WordPress знаходить його в контенті й підміняє на результат PHP-функції. Стандартні шорткоди на кшталт [gallery] та [embed] ви використовуєте постійно, навіть не замислюючись. Але власний шорткод — це важіль: один раз написали логіку, а редактор вставляє її куди завгодно трьома натисканнями.

За 10 хвилин ви створите перший робочий шорткод: від порожньої функції до тега з атрибутами та вкладеним контентом. Код реальний, запускається на будь-якому сучасному WordPress, перевірений на тестовому сайті.

💡 Швидкий огляд:

Функція add_shortcode: що приймає і як влаштована зсередини
Базовий шорткод [current_year], поточний рік у тексті
Шорткод з атрибутами [cta text="Скачать"], кастомна кнопка
Шорткод із вкладеним контентом [notice]Текст[/notice], стилізований блок
Підключення через плагін або functions.php: плюси й мінуси кожного способу
Типові помилки: echo замість return, конфлікт імен, порожній атрибут у PHP 8+

Що вміє add_shortcode і як вона працює

Функція add_shortcode, єдиний штатний спосіб зареєструвати новий шорткод у WordPress. Вона приймає два параметри:

$tag (string), ім’я шорткоду, яке ви писатимете в квадратних дужках. Тільки літери, цифри та підкреслення. Пробіли й спецсимволи & / < > [ ] = заборонені, WordPress мовчки відмовиться реєструвати такий тег.
$callback (callable), ім’я PHP-функції, яка спрацює при виявленні шорткоду. Саме вона формує той HTML, який побачить відвідувач.

Вихідний код функції, п’ять рядків логіки та дві перевірки на дурня (повний лістинг на developer.wordpress.org):

1 function add_shortcode( $tag, $callback ) {
2     global $shortcode_tags;
3  
4     if ( '' === trim( $tag ) ) {
5         _doing_it_wrong(
6             __FUNCTION__,
7             __( 'Invalid shortcode name: Empty name given.' ),
8             '4.4.0'
9         );
10         return;
11     }
12  
13     if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
14         _doing_it_wrong(
15             __FUNCTION__,
16             sprintf(
17                 /* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
18                 __( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
19                 $tag,
20                 '& / < > [ ] ='
21             ),
22             '4.4.0'
23         );
24         return;
25     }
26  
27     $shortcode_tags[ $tag ] = $callback;
28 }

Ключовий момент: $shortcode_tags, глобальний масив. WordPress зберігає в ньому всі зареєстровані шорткоди. Під час рендерингу контенту ядро проходить цим масивом і для кожного знайденого тега викликає пов’язану функцію. Звідси два наслідки:

*Реєструйте на хуку init.* Якщо повісити add_shortcode безпосередньо у файлі плагіна, вона може спрацювати до повної ініціалізації WordPress. Коректний спосіб, обгорнути в хук:

1 add_action( 'init', 'my_register_shortcodes' );
2  
3 function my_register_shortcodes() {
4     add_shortcode( 'mytag', 'my_shortcode_callback' );
5 }

Префікс, обов’язково. Глобальний масив один на всі плагіни й тему. Назвали шорткод [button], і ваш [button] мовчки перезаписав такий самий шорткод із плагіна форм. Префікс на кшталт myplugin_ або унікального скорочення вирішує проблему. У прикладах нижче я використовую префікс mysite_, у реальному проєкті замініть на свій.

Крок 1: простий шорткод без параметрів

Найкоротший шлях до робочого шорткоду, три рядки у functions.php дочірньої теми (або в плагіні Code Snippets, так безпечніше, не загубиться при оновленні теми).

Додайте цей код і збережіть:

1 add_shortcode( 'mysite_current_year', 'mysite_display_current_year' );
2  
3 function mysite_display_current_year() {
4     return date( 'Y' );
5 }

Тепер у будь-якому пості чи на сторінці напишіть [mysite_current_year]. На фронті замість шорткоду відобразиться поточний рік: «2026».

Що тут відбувається. Функція mysite_display_current_year не приймає аргументів, викликає PHP-функцію date('Y') і повертає рядок із чотирьох цифр. WordPress підставляє цей рядок точно в те місце, де стояв шорткод. Жодної магії.

Де це застосувати на практиці: рік у футері (© [mysite_current_year]), вік проєкту в тексті («працюємо з [mysite_current_year] року»), автоматичне оновлення дат на юридичних сторінках.

Шаг 2: шорткод з атрибутами

Шорткод без параметрів корисний, але справжня гнучкість починається з атрибутів. Класичний приклад, кнопка з настроюваним текстом і посиланням:

1 add_shortcode( 'mysite_cta', 'mysite_cta_button' );
2  
3 function mysite_cta_button( $atts ) {
4     $atts = shortcode_atts(
5         array(
6             'text' => 'Learn more',
7             'url'  => '#',
8         ),
9         $atts,
10         'mysite_cta'
11     );
12  
13     return sprintf(
14         '<a href="%s" class="mysite-cta-button">%s</a>',
15         esc_url( $atts['url'] ),
16         esc_html( $atts['text'] )
17     );
18 }

У редакторі використовуйте так:

1 [mysite_cta text="Download plugin" url="https://example.com/myplugin/"]

Функція shortcode_atts робить три речі водночас: об’єднує користувацькі атрибути зі значеннями за замовчуванням, фільтрує лише відомі ключі та нормалізує порожній рядок у масив (без неї під час виклику [mysite_cta] без атрибутів у PHP 8+ виникне TypeError, перший параметр callback-функції отримає порожній рядок, а не масив).

*Чому esc_url і esc_html.* Шорткод вставляє редактор, сьогодні це ви, а завтра, контент-менеджер без доступу до коду. Екранування на виході страхує від випадкового XSS, якщо в атрибут text потрапить дужка або тег.

Шаг 3: шорткод із вкладеним контентом

Деякі шорткоди обгортають фрагмент тексту: [mysite_notice]Важное сообщение[/mysite_notice]. Вкладений контент надходить у callback другим параметром, $content. Типовий сценарій, стилізований блок із попередженням:

1 add_shortcode( 'mysite_notice', 'mysite_notice_box' );
2  
3 function mysite_notice_box( $atts, $content = null ) {
4     $atts = shortcode_atts(
5         array(
6             'type' => 'info',
7         ),
8         $atts,
9         'mysite_notice'
10     );
11  
12     $class = 'notice-' . esc_attr( $atts['type'] );
13  
14     return sprintf(
15         '<div class="mysite-notice %s"><p>%s</p></div>',
16         $class,
17         do_shortcode( $content )
18     );
19 }

Зверніть увагу на do_shortcode( $content ). Якщо всередині вашого шорткоду редактор вставив інший шорткод (наприклад [mysite_current_year]), ця обгортка запустить і його. Без do_shortcode вкладені шорткоди відобразяться як текст у квадратних дужках, сирий [mysite_current_year] замість «2026».

CSS для блоку, мінімальний, для початку:

1 .mysite-notice {
2     border-left: 4px solid #2271b1;
3     background: #f0f6fc;
4     padding: 1em 1.2em;
5     margin: 1.5em 0;
6     border-radius: 4px;
7 }
8 .mysite-notice.notice-warning {
9     border-left-color: #dba617;
10     background: #fcf9e8;
11 }

Додайте стилі в style.css дочірньої теми або через Зовнішній вигляд → Налаштувати → Додатковий CSS.

Шаг 4: шорткод усередині плагіна (ООП-підхід)

Коли шорткодів стає більше трьох, functions.php перетворюється на звалище. Час виносити логіку в окремий плагін, а в ідеалі, в клас. Ось заготовка мініплагіна з одним шорткодом:

1 <?php
2 /**
3  * Plugin Name:  MySite Shortcodes
4  * Description:  Custom shortcodes for the site.
5  * Version:      1.0.0
6  * Requires PHP: 7.4
7  */
8  
9 defined( 'ABSPATH' ) || exit;
10  
11 class MySite_Shortcodes {
12  
13     public static function init() {
14         add_action( 'init', array( __CLASS__, 'register' ) );
15     }
16  
17     public static function register() {
18         add_shortcode( 'mysite_email', array( __CLASS__, 'email_obfuscated' ) );
19     }
20  
21     public static function email_obfuscated( $atts ) {
22         $atts = shortcode_atts(
23             array( 'address' => '' ),
24             $atts,
25             'mysite_email'
26         );
27  
28         if ( ! is_email( $atts['address'] ) ) {
29             return '';
30         }
31  
32         return sprintf(
33             '<a href="mailto:%1$s">%1$s</a>',
34             antispambot( $atts['address'], 1 )
35         );
36     }
37 }
38  
39 MySite_Shortcodes::init();

Розмістіть цей файл у wp-content/plugins/mysite-shortcodes/mysite-shortcodes.php та активуйте плагін в адмінці. Шорткод [mysite_email address="hello@example.com"] виведе захищене від спам-ботів посилання, функція antispambot кодує символи email в HTML-entities.

Чому клас, а не набір функцій. Простір імен: три шорткоди в класі не перетнуться зі сторонніми функціями. Плюс автозавантаження, плюс читабельний код, якщо плагін виросте до десятка шорткодів.

Тестування шорткоду перед публікацією

Після додавання коду перевірте три сценарії:

Шорткод без атрибутів. Просто [mysite_cta], має відрендеритися зі значеннями за замовчуванням (текст «Learn more», посилання #).
Шорткод з атрибутами. Повний набір параметрів, усі значення підтягнулися та відобразилися коректно.
Помилка в атрибутах. Невалідний email у [mysite_email], функція мовчки повертає порожній рядок, а не ламає сторінку.

Важливо: ніколи не використовуйте echo усередині callback-функції. Шорткод має повертати рядок через return. Якщо вивести HTML через echo, він з’явиться не на місці шорткоду, а на самому верху сторінки, WordPress запускає рендеринг шорткодів до виведення контенту. Та сама логіка, що й у фільтрів: функція віддає значення, рушій сам вирішує, куди його вставити.

Другий нюанс: якщо шорткод не відображається (бачите [mysite_cta] як текст, а не кнопку), перевірте, що функцію зареєстровано на хуку init, а не безпосередньо в тілі плагіна. Без init глобальний масив $shortcode_tags може бути ще не готовий до прийому нових тегів.

Шорткод у темі проти плагіна: що обрати

Критерій	`functions.php` теми	Окремий плагін
Швидкість старту	Швидше, файл уже завантажено	Трохи повільніше, окремий файл
Переносимість	Прив’язаний до теми	Працює з будь-якою темою
Виживаність під час оновлення	Злітає під час оновлення теми	Живе незалежно
Зручність редагування	Зовнішній вигляд → Редактор файлів теми	Редактор плагінів або FTP
Для скількох шорткодів	1-3	4+

Правило: почали з functions.php на тестовому сайті, зробили три шорткоди, виносьте в плагін. Оновлення теми через пів року не поховає вашу логіку, і перенести шорткоди на інший проєкт можна за хвилину.

⁉️🤔 Часті запитання

У чому різниця між шорткодом і блоком Gutenberg?

Шорткод — це текстовий тег у квадратних дужках, який обробляється на стороні сервера. Блок — це візуальний компонент редактора, React-компонент із налаштуваннями в бічній панелі. Шорткоди з’явилися у WordPress 2.5 (2008), блоки, у 5.0 (2018). Сьогодні блоки є основним способом вставки динамічного контенту, але шорткоди залишаються актуальними: вони простіші в розробці, не потребують знання JavaScript і працюють у будь-якому редакторі, включно з Classic Editor і конструкторами сторінок.

Шорткод — це текстовий тег, який WordPress замінює на результат PHP-функції під час виведення сторінки. На відміну від блоку Gutenberg, шорткод не має візуального інтерфейсу в редакторі: контент-менеджер пише [myshortcode] текстом, а на фронті бачить готовий HTML.

Чи можна використовувати шорткод усередині іншого шорткоду?

Так. Якщо callback-функція зовнішнього шорткоду обгортає вкладений контент у do_shortcode(), внутрішні шорткоди відпрацюють коректно: [notice][current_year][/notice] виведе стилізований блок із поточним роком. Без do_shortcode() вкладений шорткод залишиться текстом у квадратних дужках.

Вкладені шорткоди обробляються рекурсивно: WordPress проходить рядком кілька разів, доки не залишиться необроблених тегів. Але для цього зовнішній шорткод має явно викликати do_shortcode($content). Інакше рядок [current_year] так і залишиться текстом, а не перетвориться на «2026».

Чому мій шорткод не працює, відображається як текст у квадратних дужках?

Три часті причини. Перша: add_shortcode викликано до хука init, перенесіть реєстрацію всередину add_action('init', ...). Друга: одрук в імені тега: [my_shortcode] у редакторі, а зареєстровано myshortcode. Третя: callback-функція використовує echo замість return, виведення потрапляє на початок сторінки, а на місці шорткоду порожньо.

Найчастіше винен echo замість return у callback-функції. WordPress викликає обробники шорткодів до виведення основного контенту, результат echo потрапляє в буфер виведення раніше, ніж заголовок сторінки. Відкрийте вихідний код сторінки (Ctrl+U): якщо бачите HTML шорткоду на самому верху, до <html>, проблема саме в цьому.

Чи потрібно екранувати виведення шорткоду?

Обов’язково. Шорткод приймає атрибути від редактора, а отже, потенційно від будь-якого користувача з правами автора чи редактора. esc_html() для тексту, esc_url() для посилань, esc_attr() для HTML-атрибутів. Виняток, якщо ви свідомо повертаєте HTML-розмітку (як-от <div class="notice">). Але навіть тоді атрибути всередині розмітки екрануйте.

Так, екранування обов’язкове для всього, що надходить з атрибутів шорткоду або користувацького введення. Навіть якщо сьогодні шорткоди вставляєте лише ви, завтра доступ до редактора отримає контент-менеджер. esc_html() для тексту, esc_url() для посилань, esc_attr() для HTML-атрибутів рятують від випадкового або навмисного XSS.

Скільки шорткодів можна зареєструвати на одному сайті?

Технічного ліміту немає: $shortcode_tags — це звичайний PHP-масив, ви впретеся в пам’ять сервера значно пізніше, ніж у здоровий глузд. На практиці після 15-20 кастомних шорткодів варто замислитися: чи не час частину з них перенести в блоки Gutenberg? Шорткоди з унікальною логікою (email-обфускація, умовне виведення за роллю) залишайте. Шорткоди заради стилізації тексту ([highlight]) краще зробити стилем блоку або CSS-класом.

Технічно, скільки завгодно, масив $shortcode_tags не має штучного ліміту. Практично, більше 20-25 шорткодів на одному сайті свідчить про те, що частину логіки час переносити в блоки. Кожен шорткод додає накладні витрати на парсинг контенту: перед виведенням WordPress проходить по всьому масиву зареєстрованих тегів і шукає збіги в тексті посту.

Чи варто писати свої шорткоди, чи вистачить готових плагінів?

Готовий плагін покриває більшість типових задач: форми, Contact Form 7, таблиці, TablePress, сітки, будь-який page builder. Свій шорткод потрібен, коли логіка специфічна для вашого сайту і готового рішення немає: виведення кастомного поля саме в цьому місці сторінки, дата наступного вебінару з бази, персоналізоване привітання за роллю користувача.

Якщо коротко: для типового функціоналу беріть плагін і не програмуйте. Для унікальної логіки, add_shortcode + functions.php або міні-плагін. Коду в будь-якому з прикладів вище, менше десяти рядків. Освоївши ці три патерни (простий, з атрибутами, з вкладеним контентом), ви закриєте переважну більшість задач, під які взагалі пишуть кастомні шорткоди.