Хелперы в теме WordPress: как отделить подготовку данных от разметки
Хелпер темы WordPress - это обычная PHP-функция с префиксом темы, которая готовит данные для шаблона и возвращает результат, а не выводит его сама.
Прямой ответ: такое разделение дает простой эффект. Шаблон отвечает за структуру HTML, хелпер - за повторяющуюся логику подготовки. Если вы поддерживаете кастомную тему дольше полугода, этот слой почти всегда окупается.
1. Почему шаблоны перегружаются
Шаблон начинается с чистой разметки. Затем добавляется условие для CSS-класса, форматирование метаполя, проверка наличия миниатюры, выборка связанных записей. Каждое добавление по отдельности выглядит безобидно.
Проблема появляется при повторении. Один и тот же блок условий копируется в content-card.php, content-product.php, архив и поиск. Правка в одном месте не попадает в остальные. Чтение шаблона затрудняется: за условиями уже не видна разметка.
Здесь помогает не вынос побольше PHP из шаблона, а разделение ответственности. Шаблон решает, что показать. Хелпер решает, как получить и подготовить значение для показа.
2. Какие операции выносят в хелперы
Кандидат на хелпер - повторяющаяся операция подготовки, результат которой нужен в нескольких шаблонах:
- сборка CSS-классов карточки, секции, кнопки;
- получение и форматирование метаданных записи;
- подготовка атрибутов изображений -
src,srcset,alt, размеры; - форматирование дат, чисел, диапазонов цен;
- проверка условий отображения - есть ли видео, бейдж, скидка;
- выборка связанных записей с фиксированными параметрами.
Ориентир для решения:
| Вынести в хелпер | Оставить в шаблоне |
|---|---|
| сборка классов из 2-3 условий | один статический класс |
| форматирование метаполя, которое повторяется | прямой вызов the_title() без обработки |
получение URL и alt изображения с fallback | HTML-обертка 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. Когда хелпер не нужен
Проверка простая. Если функция используется один раз, не содержит условий и не упрощает чтение шаблона - оставляйте код в шаблоне. Абстракция должна уменьшать сложность, а не перемещать ее в другой каталог.
Хорошо организованные хелперы позволяют шаблонам сосредоточиться на разметке, а вспомогательным функциям - на подготовке данных. При этом сама организация остается простой: несколько файлов по назначению, понятные имена с префиксом, возврат вместо вывода.
