Twig - это мощный шаблонизатор, позволяющий создавать простые и выразительные шаблоны для фронтенда. Он широко используется в таких фреймворках, как Symfony и Drupal. Однако WordPress не поддерживает Twig нативно, поэтому, если мы хотим использовать шаблоны Twig, мы должны подключить его вручную.

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

Почему бы не использовать Twig непосредственно в WordPress?

Мы решили не интегрировать Twig напрямую в наш плагин из-за возможности конфликтов с другими плагинами.

Даже если вы разрабатываете тему, мы настоятельно рекомендуем обращать внимания на возможность конфликтов.

Итак, что же это за конфликты? Они возникают, когда несколько плагинов или комбинация плагинов и тем используют Twig, но в разных версиях.

В отличие от Node.js, PHP не поддерживает одновременное использование нескольких версий одного и того же пакета. В случае с Twig он включает специальные проверки. Если несколько плагинов или тем используют Twig, то загрузится только первая версия Twig, а остальные будут пропущены.

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

Вы можете подумать, что мало кто использует Twig в WordPress, но это не так. Более чем 105 плагинов, включая такие популярные, как Matomo Analytics, Timber и Shield Security, используют Twig.

Если вы решите использовать Twig непосредственно в своем плагине или теме, то рискуете столкнуться с конфликтом версий с одним из этих существующих плагинов или с плагинами, которые могут появиться в будущем.

Scoping с PHP Scoper

Оптимальным решением на данный момент является scoping. Scoping подразумевает добавление префикса к исходному пространству имен пакета. Такой подход широко распространен среди плагинов WordPress, и ярким примером является плагин Yoast SEO.

Если мы инкапсулируем все файлы Twig в нашем пространстве имен, то это позволит избежать конфликтов. Но как это сделать?

На помощь приходит PHP Scoper, полезная утилита доступная через Сomposer, предназначенная для решения этой задачи.

Мы не будем вдаваться в подробности использования Scoper, все достаточно просто. Для ознакомления с утилитой можно обратиться к официальной документации и прочитать эту статью.

После того как вы установили пакет и решили, что все готово, наступает реальность. Жизнь разработчика никогда не бывает такой простой. PHP Scoper требует от нас преодолеть несколько трудностей, прежде чем он позволит нам без проблем интегрировать шаблоны Twig в WordPress.

Проблемы, связанные с Twig scoping

PHP Scoper обычно хорошо работает из коробки с большинством пакетов. К сожалению, Twig является исключением. Помимо того, что Twig включает в себя набор глобальных функций (с которыми Scoper может работать), он динамически генерирует код при компиляции шаблонов. Этот генерируемый код взаимодействует с классами и функциями Twig, которые должны быть глобальными.

PHP Scoper не в состоянии обработать эти аспекты, что означает, что во время выполнения мы будем сталкиваться с ошибками типа 'function or class is not defined', поскольку некоторые части кода будут пытаться обратиться к глобально объявленным классам.

Вручную решать каждый отдельный случай нецелесообразно, так как на это потребуются недели.

Было бы полезно найти решение этой проблемы, не так ли? Особенно если учесть, что PHP Scoper поддерживает пользовательские патчи, которые, по сути, являются функциями, вызываемыми во время выполнения для исправления 'тяжелых' случаев.

Пользовательский патч в PHP Scoper

Итак, мы определили правильный подход, но нам все еще нужно приложить усилия и написать фрагмент патча.

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

Проведя небольшое исследование, я обнаружил, что любезные ребята из OnTheGoSystems (разработчики WPML) уже создали патч для этой задачи. Им тоже понадобились шаблоны Twig для своих WordPress-решений, и они великодушно решили поделиться своим решением с другими.

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

Мы создали репозиторий, включающий конфигурацию Scoper для Twig v3 с необходимыми патчами. Вы можете использовать его в своих проектах, чтобы безопасно интегрировать Twig v3 в свой плагин или тему.

Альтернативные подходы к интеграции шаблонов Twig в WordPress

Если ручная настройка Twig вам не по душе, то стоит рассмотреть альтернативные решения для интеграции шаблонов Twig в WordPress.

Одним из вариантов является фреймворк Timber, который также доступен в виде плагина. Другой вариант - плагин ACF Views, предназначенный для создания умных шаблонов (на основе Twig) для отображения контента в WordPress.

Timber - это не просто интеграция Twig, это фреймворк, который помимо интеграции Twig предлагает ряд помощников и классов. Однако существенным недостатком Timber, особенно в части использования Twig, является то, что он не применяет scoping для Twig. Используя Timber, вы, по сути, перекладываете ответственность за неконфликтность Twig с себя на автора, что потенциально может привести к проблемам совместимости.

С другой стороны, плагин ACF Views специально предназначен для работы с шаблонами. Изначально он является дополением ACF, однако для его работы достаточно базовой версии ACF, а версия Pro не является обязательной. Этот плагин позволяет создавать умные шаблоны, в которых выбранные поля поста загружаются в шаблон, и он автоматически генерирует базовую разметку (в стиле BEM), что в итоге позволяет сэкономить значительное количество времени. О преимуществах можно прочитать здесь, а более подробную информацию найти на официальной странице.

Послесловие

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

Счастливого пути! (в оригинале Happy twigging).