Главная / Блог / Хелперы в теме WordPress

Хелперы в теме WordPress: как отделить подготовку данных от разметки

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

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

1. Почему шаблоны перегружаются

Шаблон начинается с чистой разметки. Затем добавляется условие для CSS-класса, форматирование метаполя, проверка наличия миниатюры, выборка связанных записей. Каждое добавление по отдельности выглядит безобидно.

Проблема появляется при повторении. Один и тот же блок условий копируется в content-card.php, content-product.php, архив и поиск. Правка в одном месте не попадает в остальные. Чтение шаблона затрудняется: за условиями уже не видна разметка.

Здесь помогает не вынос побольше PHP из шаблона, а разделение ответственности. Шаблон решает, что показать. Хелпер решает, как получить и подготовить значение для показа.

2. Какие операции выносят в хелперы

Кандидат на хелпер - повторяющаяся операция подготовки, результат которой нужен в нескольких шаблонах:

  • сборка CSS-классов карточки, секции, кнопки;
  • получение и форматирование метаданных записи;
  • подготовка атрибутов изображений - src, srcset, alt, размеры;
  • форматирование дат, чисел, диапазонов цен;
  • проверка условий отображения - есть ли видео, бейдж, скидка;
  • выборка связанных записей с фиксированными параметрами.

Ориентир для решения:

Вынести в хелперОставить в шаблоне
сборка классов из 2-3 условийодин статический класс
форматирование метаполя, которое повторяетсяпрямой вызов the_title() без обработки
получение URL и alt изображения с fallbackHTML-обертка figure
выборка связанных записейцикл вывода уже полученных записей
проверка «показывать или нет» по нескольким полямпростое if ( has_post_thumbnail() ) вокруг одного блока

Если операция встречается один раз и занимает одну строку, отдельный хелпер обычно не нужен.

3. Как организовать файлы

Рабочая структура для небольшой и средней темы выглядит так:

theme/
├── functions.php
├── inc/
│   ├── setup.php
│   ├── enqueue.php
│   ├── post-types.php
│   └── helpers/
│       ├── template.php
│       ├── media.php
│       ├── post.php
│       └── formatting.php
├── template-parts/
└── templates/

Принципов всего три.

Первый: functions.php - точка входа. В нем только подключения и минимум вспомогательной логики загрузки. Сама логика живет в inc/.

Второй: группировка по назначению, а не один общий helpers.php на 800 строк. media.php - изображения, formatting.php - даты и числа, post.php - метаданные записей, template.php - классы и условия отображения.

Третий: предсказуемое подключение. В темах обычно используют require_once для каждого файла хелперов. Причина практическая - защита от повторного подключения и fatal error при переподключении через дочернюю тему или повторном вызове. require достаточно при строго контролируемом порядке, но в теме порядок подключения меняют чаще, чем кажется, поэтому require_once здесь - разумный вариант по умолчанию.

4. Как писать сами функции

Несколько требований закрывают большинство проблем.

Префикс обязателен. Все функции темы живут в глобальном пространстве имен, поэтому имя вида get_card_classes() рано или поздно пересечется с плагином. Префикс темы - kruglov_get_card_classes() - убирает этот риск без неймспейсов и классов.

Возврат вместо вывода. Хелпер готовит и возвращает строку, массив или null. Вывод и экранирование остаются в шаблоне. Так функцию можно переиспользовать, тестировать и комбинировать.

Типизация по возможности. Для PHP 8 в теме уместны простые типы: string, array, ?string, int. Это фиксирует контракт без лишней строгости.

Аргументы вместо чтения глобального состояния внутри. Вместо неявного get_the_ID() внутри каждого хелпера лучше принять $post_id = null и разрешить его в значение по умолчанию внутри. Функция становится явной и пригодной для архивов, выборок и REST.

Экранирование - на выводе. Внутри хелпера данные готовят, в шаблоне - экранируют: esc_html() для текста, esc_attr() для атрибутов, esc_url() для ссылок. Хелпер не должен возвращать уже частично экранированную строку, которую потом экранируют повторно.

Пример аккуратной сигнатуры:

<?php
function kruglov_get_card_classes( ?int $post_id = null ): string {
    $post_id = $post_id ?? get_the_ID();
    $classes = [ 'card' ];

    if ( has_post_thumbnail( $post_id ) ) {
        $classes[] = 'card--has-image';
    }

    if ( get_post_type( $post_id ) === 'product' ) {
        $classes[] = 'card--product';
    }

    return implode( ' ', $classes );
}

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

<article class="<?php echo esc_attr( kruglov_get_card_classes() ); ?>">

До рефакторинга тот же фрагмент выглядел так:

<?php
$classes = [ 'card' ];

if ( get_post_thumbnail_id() ) {
    $classes[] = 'card--has-image';
}

if ( get_post_type() === 'product' ) {
    $classes[] = 'card--product';
}
?>

<article class="<?php echo esc_attr( implode( ' ', $classes ) ); ?>">

Разница не в количестве строк, а в месте ответственности. Условия классов теперь живут в одном файле helpers/template.php, а шаблон показывает только структуру карточки.

5. Хелперы, template parts и компоненты

Эти три инструмента часто путают. Их удобно различать по результату:

ИнструментЧто делаетКогда подходит
Хелпервозвращает данные или строкунужно подготовить значение для нескольких шаблонов
Template partвыводит готовый HTML-кусок через get_template_part()нужен повторяющийся блок разметки с минимальными параметрами
Компонентпринимает параметры и выводит разметкунужен повторяющийся блок с вариациями, например карточка с 3-4 режимами

Хелпер не заменяет template part. Хелпер готовит классы, URL и тексты, template part раскладывает их по разметке.

6. Типичные ошибки

  • Хелпер ради каждой строки. Обертка вида kruglov_get_title() вокруг get_the_title() не упрощает, а добавляет уровень косвенности.
  • Смешивание подготовки и вывода. Функция, которая и запрашивает данные, и делает echo с куском HTML внутри, не переиспользуется и плохо проверяется.
  • Универсальность без меры. Параметры вида $args = [] с десятью флагами превращают хелпер в мини-движок. Лучше две узкие функции, чем одна с ветвлениями на все случаи.
  • Дублирование под разными именами. get_card_classes(), card_class_list(), the_card_class() в разных файлах - признак отсутствия группировки и единого нейминга.
  • Бизнес-логика внутри темы. Расчет скидок, остатков, сложной фильтрации выборок - задача уровня плагина или MU-плагина, а не темы. В теме остается подготовка к показу.

7. Когда хелпер не нужен

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

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

Частые вопросы

Чтобы не пропустить новые материалы

Короткий дайджест вечером в понедельник. Без спама.

Выберите, что получать

Обсудим ваш проект

Расскажите о вашем бизнесе, покажите текущий сайт или просто опишите задачу в свободной форме. Я изучу вводные, предложу решение и сориентирую по срокам и смете.

Отвечаю в течение нескольких часов в рабочее время.

Защита от спама – Yandex SmartCaptcha

Если вам удобнее обсудить всё текстом без заполнения форм – напишите напрямую: в Telegram или на sergei@kruglov.net

Удобнее голосом? Напишите пару слов о задаче - договоримся об удобном времени созвона на 15-20 минут, и я пришлю свой номер телефона.