PHP для WordPress: первый маленький shortcode

WordPress — одна из главных причин, почему PHP до сих пор нужен огромному числу сайтов. Но начинать лучше не с правки ядра и не с копирования кусков в случайные места. В этом уроке сделаем маленький shortcode: пользователь вставляет [ag_lesson_box title="PHP"], а WordPress выводит аккуратный блок

Главная мысль: shortcode-функция должна возвращать строку, а не делать echo

Что получится в конце

В редакторе WordPress вы вставите:

[ag_lesson_box title="PHP"]Первый shortcode работает[/ag_lesson_box]

На странице появится блок с заголовком и текстом

Код можно временно добавить в functions.php дочерней темы или лучше оформить как маленький плагин

Где писать код

Для быстрой проверки часто используют:

wp-content/themes/your-child-theme/functions.php

Но у этого пути есть риск: при смене темы shortcode пропадет. Для функциональности, которая не относится к дизайну темы, лучше мини-плагин:

wp-content/plugins/ag-lesson-box/ag-lesson-box.php

В этом уроке покажем код так, чтобы его можно было перенести в мини-плагин

Первый shortcode

Код:

<?php
add_shortcode('ag_lesson_box', 'ag_lesson_box_shortcode');

function ag_lesson_box_shortcode($atts = [], $content = null) {
    $atts = shortcode_atts(
        [
            'title' => 'Материал',
        ],
        $atts,
        'ag_lesson_box'
    );

    $title = esc_html($atts['title']);
    $text = esc_html($content ?? '');

    return '<div class="ag-lesson-box">'
        . '<strong>' . $title . '</strong>'
        . '<p>' . $text . '</p>'
        . '</div>';
}

Теперь в записи можно использовать:

[ag_lesson_box title="PHP"]Первый shortcode работает[/ag_lesson_box]

Что делает add_shortcode

Функция:

add_shortcode('ag_lesson_box', 'ag_lesson_box_shortcode');

регистрирует shortcode. Первый аргумент — имя, которое пользователь пишет в редакторе. Второй — функция, которая будет вызвана при обработке контента

Имя лучше делать уникальным и с префиксом. Просто [box] может конфликтовать с темой или другим плагином. [ag_lesson_box] безопаснее

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

Shortcode callback должен вернуть строку:

return '<div>...</div>';

Если внутри shortcode сделать echo, вывод может появиться не там, где стоит shortcode. WordPress обрабатывает контент через фильтры, поэтому результат должен вернуться как значение

Это один из самых частых багов новичка

shortcode_atts и значения по умолчанию

Функция:

shortcode_atts(
    ['title' => 'Материал'],
    $atts,
    'ag_lesson_box'
)

берет атрибуты пользователя и добавляет значения по умолчанию. Если пользователь напишет:

[ag_lesson_box]Текст[/ag_lesson_box]

заголовок будет Материал

Если напишет:

[ag_lesson_box title="Важно"]Текст[/ag_lesson_box]

заголовок станет Важно

Escaping: esc_html

Данные из shortcode нельзя выводить без обработки. Пользователь может вставить HTML. Для простого текстового вывода используем:

esc_html($atts['title'])
esc_html($content ?? '')

Если атрибут идет в HTML-атрибут, нужен esc_attr. Если нужно разрешить ограниченный HTML, это отдельная задача и другие функции. Для первого shortcode текстовый безопасный вывод лучше

Мини-плагин

Создайте папку:

wp-content/plugins/ag-lesson-box

Файл ag-lesson-box.php:

<?php
/**
 * Plugin Name: AG Lesson Box
 * Description: Учебный shortcode для блока урока.
 * Version: 1.0.0
 */

add_shortcode('ag_lesson_box', 'ag_lesson_box_shortcode');

function ag_lesson_box_shortcode($atts = [], $content = null) {
    $atts = shortcode_atts(['title' => 'Материал'], $atts, 'ag_lesson_box');

    return '<div class="ag-lesson-box">'
        . '<strong>' . esc_html($atts['title']) . '</strong>'
        . '<p>' . esc_html($content ?? '') . '</p>'
        . '</div>';
}

Активируйте плагин в админке WordPress и проверьте shortcode в записи

Частые ошибки

Shortcode выводится как текст. Код не подключен, плагин не активирован или shortcode зарегистрирован слишком поздно

Блок появляется в начале страницы. В callback используется echo вместо return

Конфликт имени shortcode. Другой плагин использует то же имя. Добавьте уникальный префикс

HTML ломается от атрибутов. Не забывайте esc_html и esc_attr

Что может быть еще интересно по этой теме

Лучше functions.php или плагин? Для временной проверки можно functions.php дочерней темы. Для функциональности сайта лучше мини-плагин

Можно ли вставлять PHP прямо в запись? Нельзя и не нужно. Shortcode как раз дает безопасный способ вызвать подготовленную функцию из контента

Нужно ли делать shortcode в эпоху блоков? Да, shortcodes до сих пор встречаются, особенно в старых сайтах, плагинах и простых интеграциях

Можно ли добавить CSS? Да, но лучше подключать стили через WordPress hooks, а не вставлять большие <style> прямо в shortcode

Что открыть дальше

• PHP с нуля: первый файл и вывод на страницу — если PHP-синтаксис еще неустойчив.
• Формы в PHP: GET, POST и первая обработка — понадобится для shortcode с формой.
• Массивы в PHP: обычные, ассоциативные и foreach — WordPress API часто возвращает массивы.
• Ошибки PHP: белый экран, error log и display_errors — поможет, если сайт упал после вставки кода.