Как программно использовать шорткоды WordPress в PHP: полное руководство для разработчиков

10.01.2026
70289

7 мин
6

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

Данное руководство предназначено для тех, кто хочет не только использовать шорткоды, но и интегрировать их программно в свои темы, плагины или кастомные PHP-скрипты. Мы рассмотрим, как вызывать шорткоды из PHP, создавать собственные, передавать им данные и решать распространенные проблемы, тем самым расширяя функциональность WordPress и делая ваш код более гибким и модульным.

Основы шорткодов WordPress и их программный вызов

Что такое шорткоды WordPress и зачем их использовать?

Шорткоды WordPress – это мощный инструмент, позволяющий добавлять сложную функциональность на страницы, записи или виджеты WordPress, не прибегая к написанию сложного кода напрямую в контенте. Они представляют собой простые теги, заключенные в квадратные скобки, например, [my_shortcode]. Основное преимущество шорткодов заключается в отделении логики представления от контента, что делает редактирование и поддержку сайта проще и эффективнее.

Разработчики используют шорткоды для встраивания галерей, форм, видео, кнопок и других интерактивных элементов. Программное использование шорткодов открывает еще больше возможностей, позволяя динамически генерировать контент на основе логики PHP.

Функция do_shortcode(): простой способ вызова шорткодов в PHP

Функция do_shortcode() – это основной инструмент для вызова шорткодов в PHP-коде. Она принимает строку, содержащую шорткод, и возвращает HTML-код, сгенерированный этим шорткодом.

Пример:

<?php
$content = '[my_shortcode attribute="value"]';
echo do_shortcode( $content );
?>

В этом примере шорткод [my_shortcode attribute="value"] будет обработан, и функция do_shortcode() вернет результат его выполнения, который затем будет выведен на странице. do_shortcode() позволяет интегрировать шорткоды в шаблоны тем, плагины и другие PHP-файлы, предоставляя гибкий способ расширения функциональности WordPress.

Что такое шорткоды WordPress и зачем их использовать?

Шорткоды WordPress представляют собой небольшие фрагменты кода, заключенные в квадратные скобки, такие как или [my_custom_shortcode]. Они действуют как макросы, позволяя пользователям вставлять сложный контент или вызывать определенную функциональность простым, интуитивно понятным способом, не требующим прямого написания HTML или PHP-кода.

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

Функция do_shortcode(): простой способ вызова шорткодов в PHP

После того, как мы оценили преимущества шорткодов, следующим шагом в их программном использовании является освоение функции do_shortcode(). Это ключевая функция WordPress, которая позволяет обрабатывать и выполнять шорткоды, находящиеся внутри любой заданной строки PHP. В отличие от автоматической обработки шорткодов, которая происходит в the_content(), do_shortcode() предоставляет разработчику полный контроль над тем, где и когда шорткод будет интерпретирован.

Синтаксис `do_shortcode()`:

do_shortcode( string $content ): string

Функция принимает один обязательный аргумент: строку $content, которая может содержать один или несколько шорткодов. Она возвращает обработанную строку, где все найденные шорткоды заменены на их сгенерированное содержимое.

Пример использования:

Представьте, что вам нужно вывести галерею или кнопку в пользовательском мета-поле или в шаблоне темы, не используя при этом the_content():

$my_custom_content = 'Добро пожаловать на наш сайт! Вот наша последняя .';
echo do_shortcode( $my_custom_content );

// Или для вывода простой кнопки
$button_shortcode = '[button link="https://example.com" text="Узнать больше"]';
echo do_shortcode( $button_shortcode );

Таким образом, do_shortcode() обеспечивает гибкость в интеграции функциональности шорткодов в любой части вашего PHP-кода, не ограничиваясь областью основного контента записи.

Регистрация и создание собственных шорткодов

WordPress Shortcode API позволяет разработчикам создавать собственные шорткоды, расширяя функциональность движка.

Использование Shortcode API: функция `add_shortcode()`

Для регистрации нового шорткода используется функция add_shortcode(). Она принимает два параметра:

Метка шорткода: Текст, который будет использоваться внутри квадратных скобок (например, my_shortcode).
Функция обратного вызова (callback function): PHP-функция, которая будет выполняться при обнаружении шорткода.

function my_shortcode_handler( $atts, $content = null ) {
    // Логика обработки шорткода
    return '<div>' . $content . '</div>';
}
add_shortcode( 'my_shortcode', 'my_shortcode_handler' );

В этом примере мы зарегистрировали шорткод my_shortcode, который оборачивает содержимое шорткода в <div>.

Обработка атрибутов и содержимого шорткода в PHP

Функция обратного вызова принимает два аргумента:

$atts: Массив атрибутов шорткода. Атрибуты задаются в шорткоде как [my_shortcode attribute1="value1" attribute2="value2"].
$content: Содержимое между открывающим и закрывающим тегами шорткода (если шорткод парный). Если шорткод одиночный, то $content будет null.

Для извлечения значений атрибутов можно использовать функцию shortcode_atts():

function my_shortcode_handler( $atts, $content = null ) {
    $atts = shortcode_atts(
        array(
            'attribute1' => 'default_value',
            'attribute2' => 'another_default',
        ),
        $atts,
        'my_shortcode'
    );

    $attribute1 = $atts['attribute1'];
    $attribute2 = $atts['attribute2'];

    return '<div data-attribute1="' . esc_attr( $attribute1 ) . '" data-attribute2="' . esc_attr( $attribute2 ) . '">' . do_shortcode($content) . '</div>';
}

Важно использовать esc_attr() для экранирования атрибутов, чтобы предотвратить XSS-уязвимости. Функция do_shortcode() применена к $content, чтобы разрешить вложенные шорткоды.

Использование Shortcode API: функция add_shortcode()

Для регистрации нового шорткода в WordPress используется функция add_shortcode(). Это основной компонент Shortcode API, позволяющий связать уникальный тег шорткода с вашей PHP-функцией, которая будет отвечать за генерацию содержимого. Функция add_shortcode() принимает два обязательных параметра:

$tag (строка, обязательный): Уникальный тег шорткода, который будет использоваться в редакторе или при вызове с помощью do_shortcode() (например, [мой_шорткод]).
$func (строка/массив/callable, обязательный): Имя PHP-функции или callable, которая будет выполняться при обнаружении шорткода. Эта функция должна возвращать генерируемый контент, а не выводить его напрямую (echo).

Пример регистрации простого шорткода:

function my_custom_shortcode_handler() {
    return "Это контент из моего собственного шорткода!";
}
add_shortcode( 'мой_шорткод', 'my_custom_shortcode_handler' );

Таким образом, WordPress узнает, какая функция должна быть вызвана при встрече с [мой_шорткод], и использует ее возвращаемое значение.

Обработка атрибутов и содержимого шорткода в PHP

Функция-обработчик, зарегистрированная через add_shortcode(), принимает два основных аргумента:

$atts: Массив атрибутов шорткода. Атрибуты задаются в шорткоде как [myshortcode attr1="value1" attr2="value2"]. Если атрибуты не указаны, $atts может быть пустым массивом или иметь значения по умолчанию, заданные при регистрации шорткода с помощью функции shortcode_atts(). Она позволяет объединить атрибуты, предоставленные пользователем, со значениями по умолчанию.
$content: Содержимое между открывающим и закрывающим тегами шорткода (если шорткод используется как заключающий). Например, для шорткода [myshortcode]Какой-то контент[/myshortcode], $content будет содержать строку "Какой-то контент". Если шорткод самозакрывающийся (например, [myshortcode]), то $content будет null.

Пример обработки атрибутов:

function my_shortcode_handler( $atts, $content = null ) {
    $atts = shortcode_atts( array(
        'width' => '200',
        'height' => '100',
        'color' => 'red'
    ), $atts, 'myshortcode' );

    $width = esc_attr( $atts['width'] );
    $height = esc_attr( $atts['height'] );
    $color = esc_attr( $atts['color'] );

    $output = '<div style="width:' . $width . 'px; height:' . $height . 'px; background-color:' . $color . ';">';
    $output .= do_shortcode( $content ); // Обрабатываем вложенные шорткоды
    $output .= '</div>';

    return $output;
}
add_shortcode( 'myshortcode', 'my_shortcode_handler' );

В этом примере shortcode_atts() объединяет переданные атрибуты со значениями по умолчанию, обеспечивая наличие всех ожидаемых атрибутов. Функция esc_attr() используется для безопасной обработки атрибутов перед их использованием в HTML.

Интеграция шорткодов в шаблоны тем и плагины

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

Вызов шорткодов в файлах тем (например, page.php)

Чтобы использовать шорткод в файле темы, например page.php, достаточно вызвать функцию do_shortcode() и передать ей шорткод в виде строки:

<?php
echo do_shortcode( '[my_shortcode attribute="value"]' );
?>

Это позволит вставить динамически сгенерированный контент шорткода в нужное место шаблона.

Управление шорткодами внутри плагинов

В плагинах шорткоды определяются и регистрируются, как было описано ранее. Для их использования в коде плагина также применяется функция do_shortcode().

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

<?php
/*
Plugin Name: My Shortcode Plugin
*/

function my_shortcode_handler( $atts ) {
  $atts = shortcode_atts( array(
    'option' => 'default',
  ), $atts );

  if ( $atts['option'] == 'special' ) {
    return 'Special content';
  } else {
    return 'Default content';
  }
}
add_shortcode( 'my_plugin_shortcode', 'my_shortcode_handler' );

function my_plugin_function() {
  return do_shortcode( '[my_plugin_shortcode option="special"]' );
}
add_filter( 'the_content', 'my_plugin_function' );
?>

В этом примере шорткод my_plugin_shortcode регистрируется в плагине и затем вызывается внутри функции my_plugin_function, которая добавляет контент шорткода к основному контенту страницы через фильтр the_content.

Вызов шорткодов в файлах тем (например, page.php)

Интеграция шорткодов непосредственно в файлы шаблонов вашей темы WordPress, такие как page.php, single.php или footer.php, является мощным способом динамического управления контентом и функциональностью. Используя уже знакомую нам функцию do_shortcode(), вы можете вывести любой зарегистрированный шорткод в нужном месте шаблона.

Например, если у вас есть шорткод [my_custom_gallery id="123"], который вы хотите отобразить на определенной странице, его можно вызвать так:

<?php echo do_shortcode('[my_custom_gallery id="123"]'); ?>

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

Управление шорткодами внутри плагинов

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

Пример:

Регистрация шорткода в плагине:

В главном файле плагина, например my-plugin.php, используйте add_shortcode():

<?php
/*
Plugin Name: My Shortcode Plugin
*/
function my_shortcode_handler( $atts ) {
    return '<div>Содержимое шорткода из плагина.</div>';
}
add_shortcode( 'my_plugin_shortcode', 'my_shortcode_handler' );
?>

Использование шорткода:

Теперь шорткод [my_plugin_shortcode] можно использовать в любом месте сайта.
Преимущества:
- Модульность: легко добавлять и удалять функциональность.
- Удобство: пользователи могут добавлять функциональность без знания кода.
- Поддержка тем: шорткоды работают независимо от используемой темы.

Продвинутые сценарии и решение проблем

Передача параметров в шорткоды из PHP

Для передачи параметров в шорткод из PHP используйте массив атрибутов в функции do_shortcode(). Это позволяет динамически изменять поведение шорткода.

$atts = array(
    'параметр1' => 'значение1',
    'параметр2' => 'значение2'
);

echo do_shortcode('[имя_шорткода параметр1="' . $atts['параметр1'] . '" параметр2="' . $atts['параметр2'] . '"]');

Проблемы с подключением CSS/JS и их решение

Шорткоды, вызванные через do_shortcode(), могут не подключать CSS/JS автоматически. Чтобы это исправить, необходимо вручную регистрировать и подключать стили и скрипты в момент обработки шорткода. Используйте функции wp_enqueue_scripts или admin_enqueue_scripts для подключения ресурсов, убедившись, что они вызываются только при необходимости.

Например:

function my_shortcode_function($atts) {
    wp_enqueue_style( 'my-shortcode-style', '/путь/к/стилю.css' );
    wp_enqueue_script( 'my-shortcode-script', '/путь/к/скрипту.js', array( 'jquery' ), '1.0.0', true );

    // ... логика шорткода ...
}
add_shortcode('my_shortcode', 'my_shortcode_function');

Это обеспечит подключение необходимых ресурсов при вызове шорткода.

Передача параметров в шорткоды из PHP

Для максимальной гибкости вы можете передавать динамические параметры в ваши шорткоды прямо из PHP. Это особенно полезно, когда данные для шорткода генерируются в коде или извлекаются из базы данных. Вы просто формируете строку шорткода, включая необходимые атрибуты, а затем передаете ее функции do_shortcode(). Например, если у вас есть шорткод [my_shortcode id="123" title="Мой заголовок"], вы можете создать его программно:

$item_id = get_the_ID(); // Получаем ID текущей записи
$item_title = get_the_title(); // Получаем заголовок

$shortcode_string = '[my_shortcode id="' . esc_attr( $item_id ) . '" title="' . esc_attr( $item_title ) . '"]';
echo do_shortcode( $shortcode_string );

Таким образом, шорткод получит актуальные данные, что значительно расширяет его функциональность и адаптивность.

Проблемы с подключением CSS/JS и их решение

Одним из распространенных затруднений при программном вызове шорткодов через do_shortcode() является некорректное подключение связанных с ними CSS и JavaScript файлов. Это происходит потому, что многие скрипты и стили регистрируются и ставятся в очередь через хук wp_enqueue_scripts, который, возможно, уже отработал или не вызывается в контексте программного вызова шорткода.

Решения:

Отложенное подключение: Убедитесь, что ваши скрипты и стили регистрируются и ставятся в очередь внутри функции-обработчика шорткода с помощью wp_enqueue_script() и wp_enqueue_style(), но только если они еще не были поставлены в очередь. Это можно сделать, привязав эти функции к хуку wp_enqueue_scripts или wp_footer/wp_head и используя флаг, чтобы предотвратить повторное добавление.
Условное подключение: Внутри функции шорткода можно проверить, был ли уже подключен необходимый скрипт/стиль, используя wp_script_is() или wp_style_is(), и подключать их только при необходимости. Это гарантирует, что ресурсы будут доступны, но не будут дублироваться.

Сравнение и лучшие практики

`do_shortcode()` vs `the_content()`: когда что использовать

do_shortcode() предназначен для точечного вызова шорткодов, особенно когда нужно обработать шорткод вне основного контента записи, например, в виджетах или произвольных областях шаблона. the_content() фильтрует весь контент записи, применяя все зарегистрированные шорткоды.

Используйте do_shortcode(), когда нужно:

Обработать конкретный шорткод.
Вывести результат шорткода в определенном месте шаблона.

the_content() подходит, когда нужно:

Обработать все шорткоды в контенте записи.
Обеспечить стандартную обработку контента WordPress.

do_shortcode() vs the_content(): когда что использовать

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

the_content() напротив, является фильтром WordPress, который автоматически применяет шорткоды ко всему основному контенту записи (тексту записи, отображаемому на странице). Использовать the_content() напрямую для обработки шорткодов вне основного контента не рекомендуется, так как это может привести к нежелательным побочным эффектам и проблемам с производительностью. Выбор между ними зависит от контекста: для общего контента — the_content(), для точечной обработки — do_shortcode().

Заключение

Мы рассмотрели широкий спектр аспектов программного использования шорткодов WordPress в PHP, от основ do_shortcode() до создания собственных сложных решений. Понимание Shortcode API и лучших практик, таких как валидация данных и оптимизация, позволяет разработчикам создавать гибкие, масштабируемые и безопасные веб-проекты. Применяя эти знания, вы сможете значительно расширить функциональность своих тем и плагинов, делая их более динамичными и мощными.

Добавить комментарий

Как эффективно удалить ресурсы, блокирующие рендеринг, в WordPress и ускорить ваш сайт?

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

1
2026

Как правильно лицензируется программное обеспечение WordPress для успешного использования?

WordPress давно перестал быть просто платформой для блогов, превратившись в мощный инструмент для создания любых типов веб-сайтов, от корпоративных порталов до крупных интернет-магазинов.

1
2026

Насколько безопасен WordPress на самом деле, и как защитить свой сайт от взлома?

WordPress является самой популярной CMS в мире, управляя миллионами сайтов.

2
2026

Как программно использовать шорткоды WordPress в PHP: полное руководство для разработчиков

Основы шорткодов WordPress и их программный вызов

Что такое шорткоды WordPress и зачем их использовать?

Функция do_shortcode(): простой способ вызова шорткодов в PHP

Что такое шорткоды WordPress и зачем их использовать?

Функция do_shortcode(): простой способ вызова шорткодов в PHP

Синтаксис `do_shortcode()`:

Пример использования:

Регистрация и создание собственных шорткодов

Использование Shortcode API: функция `add_shortcode()`

Обработка атрибутов и содержимого шорткода в PHP

Использование Shortcode API: функция add_shortcode()

Обработка атрибутов и содержимого шорткода в PHP

Интеграция шорткодов в шаблоны тем и плагины

Вызов шорткодов в файлах тем (например, page.php)

Управление шорткодами внутри плагинов

Вызов шорткодов в файлах тем (например, page.php)

Управление шорткодами внутри плагинов

Продвинутые сценарии и решение проблем

Передача параметров в шорткоды из PHP

Проблемы с подключением CSS/JS и их решение

Передача параметров в шорткоды из PHP

Проблемы с подключением CSS/JS и их решение

Сравнение и лучшие практики

`do_shortcode()` vs `the_content()`: когда что использовать

Рекомендации по безопасному и эффективному использованию шорткодов в PHP

do_shortcode() vs the_content(): когда что использовать

Рекомендации по безопасному и эффективному использованию шорткодов в PHP

Заключение

Добавить комментарий

Как программно использовать шорткоды WordPress в PHP: полное руководство для разработчиков

Основы шорткодов WordPress и их программный вызов

Что такое шорткоды WordPress и зачем их использовать?

Функция do_shortcode(): простой способ вызова шорткодов в PHP

Что такое шорткоды WordPress и зачем их использовать?

Функция do_shortcode(): простой способ вызова шорткодов в PHP

Синтаксис do_shortcode():

Пример использования:

Регистрация и создание собственных шорткодов

Использование Shortcode API: функция add_shortcode()

Обработка атрибутов и содержимого шорткода в PHP

Использование Shortcode API: функция add_shortcode()

Обработка атрибутов и содержимого шорткода в PHP

Интеграция шорткодов в шаблоны тем и плагины

Вызов шорткодов в файлах тем (например, page.php)

Управление шорткодами внутри плагинов

Вызов шорткодов в файлах тем (например, page.php)

Управление шорткодами внутри плагинов

Продвинутые сценарии и решение проблем

Передача параметров в шорткоды из PHP

Проблемы с подключением CSS/JS и их решение

Передача параметров в шорткоды из PHP

Проблемы с подключением CSS/JS и их решение

Сравнение и лучшие практики

do_shortcode() vs the_content(): когда что использовать

Рекомендации по безопасному и эффективному использованию шорткодов в PHP

do_shortcode() vs the_content(): когда что использовать

Рекомендации по безопасному и эффективному использованию шорткодов в PHP

Заключение

Добавить комментарий

Как эффективно удалить ресурсы, блокирующие рендеринг, в WordPress и ускорить ваш сайт?

Как правильно лицензируется программное обеспечение WordPress для успешного использования?

Насколько безопасен WordPress на самом деле, и как защитить свой сайт от взлома?

Синтаксис `do_shortcode()`:

Использование Shortcode API: функция `add_shortcode()`

`do_shortcode()` vs `the_content()`: когда что использовать