Как ревьюить и рефакторить старую тему WordPress

Пятилетняя тема WordPress редко требует немедленного переписывания с нуля. Чаще проблема в другом: один и тот же блок собирается в нескольких шаблонах, CSS подключается прямо в header.php, запросы дублируются, а любое изменение превращается в ручную проверку десятков страниц. Безопасный рефакторинг начинается не с переименования файлов, а с карты поведения темы, списка регрессий и небольших замен, которые можно проверить отдельно.

Сначала зафиксируйте границы темы

Ниже речь о классической теме WordPress 6.x, а не о блочной теме с Site Editor. До изменений запишите версию WordPress, версию PHP, активные плагины, используемую дочернюю тему и способ деплоя. Если эти данные неизвестны, их нужно получить до ревью: иначе ошибка темы может оказаться несовместимостью плагина или окружения.

Соберите минимальный набор проверок:

• главная, архив рубрики, архив метки и страница поиска;
• одиночная запись, страница, запись без изображения и запись с длинным заголовком;
• форма комментариев, меню, виджеты, пагинация и 404;
• мобильная версия, пользователь без авторизации и пользователь с ролью редактора;
• страницы с отключёнными или временно заменёнными плагинами, если тема от них зависит.

Зафиксируйте не только скриншоты, но и факты: какие CSS и JavaScript загружены, сколько SQL-запросов выполняется, есть ли PHP-предупреждения, какие шаблоны WordPress выбрал для страницы. Для замеров подойдёт Query Monitor, а для серверных логов — стандартный журнал PHP и веб-сервера. Конкретные цифры до и после не стоит выдумывать: сравнение имеет смысл только на одной копии сайта, с одинаковыми данными и настройками кеша.

Цель ревью старой темы — не сделать код красивее. Цель — уменьшить число мест, где одно изменение может незаметно сломать сайт.

Что искать на первом проходе

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

Дублирование разметки и логики

В старой теме один и тот же карточный блок часто встречается в index.php, archive.php и файле шаблона страницы. Сначала вынесите только повторяющуюся разметку в подключаемый шаблон через штатный механизм WordPress, а не создавайте собственную систему загрузки файлов. Перед этим проверьте, какие переменные ожидает блок: глобальный объект записи, изображение, рубрику и произвольные поля.

Отдельно отмечайте смешение ролей. Файл шаблона должен собирать страницу, а не регистрировать меню, создавать таблицы базы данных и запускать несколько независимых запросов. Регистрацию возможностей темы переносите в functions.php или в отдельный файл темы; бизнес-логику, которая должна работать без темы, — в плагин.

Запросы внутри цикла

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

На ревью задавайте конкретные вопросы:

• можно ли получить значение из уже загруженного объекта записи;
• не выполняется ли один и тот же запрос повторно для каждой карточки;
• не создаёт ли фильтр новый запрос при каждом вызове шаблонной функции;
• есть ли пагинация и ограничение количества записей;
• что произойдёт, если плагин, добавляющий произвольное поле, отключить.

Подключение стилей и скриптов

Вызовы <link> и <script> в header.php и footer.php — сигнал для отдельной проверки. В классической теме ресурсы регистрируют и подключают через хук wp_enqueue_scripts. Так WordPress и плагины могут видеть зависимости, версию ресурса и место загрузки.

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

Данные без экранирования

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

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

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

Три стратегии рефакторинга

После инвентаризации выберите не «самый современный» вариант, а такой, который выдержит ограничения проекта: сроки, обратную совместимость и доступ к продакшену.

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

Как проводить изменения по одному риску

1. Зафиксируйте контракт шаблона

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

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

2. Отделите регистрацию от вывода

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

Проверка: после очистки кеша меню и виджеты доступны в административной панели, а CSS и JavaScript подключаются только на нужных страницах.

3. Заменяйте опасные места минимальными патчами

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

<?php
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'site-theme',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get('Version')
    );
});

Этот фрагмент рассчитан на WordPress 6.x и PHP 8.x. Если в теме уже используется дочерняя тема, get_stylesheet_uri() указывает на её таблицу стилей; путь к файлам родительской темы нужно проверять отдельно, а не заменять механически.

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

4. Уберите неиспользуемые зависимости

Удаляйте библиотеку только после поиска её обработчиков, классов и CSS-селекторов по всей теме и дочерней теме. Проверяйте не только главную: слайдер или скрипт меню может использоваться на странице контактов, в виджете или в мобильной навигации.

Проверка: открыты все типы страниц из исходного списка, меню работает клавиатурой, а в консоли нет ошибок JavaScript.

Что писать в ревью-комментариях

Фраза «код нужно улучшить» не помогает автору и не фиксирует риск. Хорошее замечание описывает место, последствие и проверяемое действие.

• Вместо: «вынести в функцию». Пишите: «Этот HTML повторяется в трёх шаблонах; изменение ссылки нужно будет внести трижды. Вынесите общий блок и проверьте архив, поиск и страницу записи».
• Вместо: «небезопасный вывод». Пишите: «Значение пользовательского поля выводится в атрибут без контекстного экранирования. Проверьте кавычки и специальные символы на тестовой записи».
• Вместо: «лишний запрос». Пишите: «Запрос выполняется внутри цикла карточек. Сравните число запросов на архиве из десяти записей до и после изменения».
• Вместо: «старый WordPress-код». Пишите: «Нужно подтвердить минимальную версию WordPress и PHP. Без этого нельзя безопасно менять поведение функции или синтаксис».

Что ломается чаще всего

Дочерняя тема теряет переопределение

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

Плагин рассчитывает на старый хук

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

Кеш скрывает результат

После рефакторинга вы можете видеть старый HTML из кеша страницы, CDN или браузера. Тестируйте на копии сайта с понятным способом очистки кеша и фиксируйте, какой слой был сброшен. Инвалидация кеша — отдельная задача; здесь важно не принять старый ответ за результат нового кода.

Тема зависит от плагина сильнее, чем кажется

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

Что делать дальше

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

В продакшене дальше смотрите не только на время ответа. Отслеживайте PHP-предупреждения, ошибки JavaScript, долю 404 для ресурсов, количество запросов к базе и страницы, на которых выросло время генерации. Когда карта зависимостей станет полной, можно решать, нужен ли постепенный рефакторинг или действительно пора переписывать тему.