Создание собственного плагина для WordPress: header, хуки и шорткоды на практике

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

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

Структура плагина и заголовок основного файла

Плагин WordPress размещается в папке wp-content/plugins/. Самый простой плагин может состоять из единственного PHP-файла, но хорошей практикой считается создание отдельной папки для каждого плагина. Например, вы создаёте папку wp-content/plugins/sayt-uz-tools/ и помещаете внутрь основной файл sayt-uz-tools.php. Чтобы WordPress распознал плагин, в начале этого файла обязательно нужно написать специальный комментарий — заголовок плагина. Именно этот заголовок определяет информацию, которая отображается в списке плагинов административной панели.

<?php
/**
 * Plugin Name: Sayt UZ Tools
 * Plugin URI:  https://sayt.uz/plugins/sayt-uz-tools
 * Description: Пользовательские шорткоды и настройки для сайта.
 * Version:     1.0.0
 * Author:      Sayt UZ
 * Author URI:  https://sayt.uz
 * License:     GPL-2.0+
 * Text Domain: sayt-uz-tools
 */

// Запрет прямого доступа
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

В заголовке обязательным является как минимум поле Plugin Name — остальные поля необязательны, но их заполнение придаёт плагину профессиональный вид. Проверка ABSPATH в самом низу очень важна: она блокирует прямой доступ к файлу через браузер и гарантирует, что код будет запускаться только через ядро WordPress. Это первый шаг безопасности, который должен присутствовать в каждом файле плагина без исключения.

Система хуков: action и filter

Сердце расширяемости WordPress — это система хуков. Хуки делятся на два типа: action и filter. Action позволяет запустить ваш код в определённой точке рабочего процесса WordPress, например выполнить какое-то действие при загрузке страницы или при сохранении записи. Filter же позволяет изменить данные перед их выводом на экран, например добавить дополнительный контент к тексту записи перед её отображением. Чтобы понять разницу, запомните простое правило: action выполняет какое-то действие, а filter изменяет данные и обязательно возвращает значение.

// Пример action: добавить текст в подвал
function sayt_uz_footer_text() {
    echo '<p style="text-align:center">Разработано Sayt.uz</p>';
}
add_action( 'wp_footer', 'sayt_uz_footer_text' );

// Пример filter: добавить заметку в конец записи
function sayt_uz_append_notice( $content ) {
    if ( is_single() ) {
        $content .= '<p class="notice">Понравилась статья? Поделитесь!</p>';
    }
    return $content;
}
add_filter( 'the_content', 'sayt_uz_append_notice' );

В этом примере add_action говорит WordPress: «когда отрисовывается подвал, вызови мою функцию», а add_filter командует: «прежде чем показать текст записи, пропусти его через мою функцию». Функция-фильтр всегда обязана возвращать изменённое значение — если вы забудете return, текст записи окажется пустым. Это одна из самых распространённых ошибок, поэтому при работе с фильтрами всегда помните о возвращаемом значении.

Практический плагин: шорткод и страница настроек

Теперь создадим что-то по-настоящему полезное. Шорткод — это механизм, который позволяет вставить в запись или страницу простую запись вроде [sayt_button], а на её месте выводится полноценный HTML. Это даёт редакторам контента возможность добавлять сложные элементы без написания кода. В следующем примере мы создадим шорткод, выводящий настраиваемую кнопку, где текст и ссылка передаются как параметры.

function sayt_uz_button_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'text' => 'Связаться',
        'url'  => '#',
    ), $atts, 'sayt_button' );

    $text = esc_html( $atts['text'] );
    $url  = esc_url( $atts['url'] );

    return '<a class="sayt-btn" href="' . $url . '">' . $text . '</a>';
}
add_shortcode( 'sayt_button', 'sayt_uz_button_shortcode' );

Теперь, если редактор напишет в любой записи [sayt_button text="Заказать" url="/order"], появится красивая кнопка. Обратите внимание, что мы использовали функции esc_html и esc_url — они очищают выводимые данные и защищают от XSS-атак. Очистка любых данных, пришедших от пользователя, перед их выводом на экран — это золотое правило безопасности WordPress, которым нельзя пренебрегать.

Плагинам часто требуется страница настроек. Чтобы добавить новый раздел в админ-меню, мы используем хук admin_menu, а для сохранения настроек применяем nonce и санитизацию данных.

function sayt_uz_admin_menu() {
    add_options_page(
        'Sayt UZ Tools',
        'Sayt UZ Tools',
        'manage_options',
        'sayt-uz-tools',
        'sayt_uz_settings_page'
    );
}
add_action( 'admin_menu', 'sayt_uz_admin_menu' );

function sayt_uz_settings_page() {
    if ( isset( $_POST['sayt_uz_save'] ) &&
         check_admin_referer( 'sayt_uz_settings', 'sayt_uz_nonce' ) ) {
        $val = sanitize_text_field( $_POST['sayt_uz_title'] );
        update_option( 'sayt_uz_title', $val );
        echo '<div class="updated"><p>Сохранено</p></div>';
    }
    $title = esc_attr( get_option( 'sayt_uz_title', '' ) );
    echo '<div class="wrap"><h1>Настройки</h1>';
    echo '<form method="post">';
    wp_nonce_field( 'sayt_uz_settings', 'sayt_uz_nonce' );
    echo '<input type="text" name="sayt_uz_title" value="' . $title . '">';
    echo '<input type="submit" name="sayt_uz_save" value="Сохранить" class="button-primary">';
    echo '</form></div>';
}

Лучшие практики: префикс и безопасность

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

В отношении безопасности всегда помните три принципа. Во-первых, любые данные, пришедшие от пользователя, перед сохранением очищайте функциями вроде sanitize_text_field. Во-вторых, перед выводом на экран экранируйте их с помощью esc_html, esc_url или esc_attr. В-третьих, в любой форме используйте nonce — создавайте его через wp_nonce_field и проверяйте через check_admin_referer. Nonce — это специальный токен, подтверждающий, что запрос действительно пришёл с вашего сайта, и защищающий от CSRF-атак.

Активация, тестирование и распространение

При активации и деактивации плагина может потребоваться выполнить особые действия, например создать таблицу в базе данных или установить значения по умолчанию. Для этого используются функции register_activation_hook и register_deactivation_hook. После написания плагина активируйте его в разделе «Плагины» административной панели WordPress и убедитесь, что не появляются сообщения об ошибках. Во время тестирования включите режим WP_DEBUG — тогда будут видны все предупреждения PHP, что помогает довести код до совершенства.

Когда ваш плагин готов и надёжен, его можно распространять. Самый простой способ — упаковать папку в ZIP-архив и установить через функцию «Загрузить плагин» административной панели WordPress. Если же вы хотите представить плагин широкой публике, его можно отправить в официальный каталог WordPress.org — там проверяется соответствие кода лицензии GPL и требованиям безопасности. Навык написания собственных плагинов превращает вас из обычного пользователя WordPress в настоящего разработчика и открывает перед вашим сайтом дверь к безграничным возможностям.