Отладка Twig шаблонов

Другие статьи серии Twig

При отладке переменных в Twig шаблоне нужно учитывать некоторые особенности шаблонизатора. Во-первых, Twig не позволит вам вызывать php функции, которые вы могли использовать при отладке php шаблонов: var_dump(), print_r(), dpm() (функция модуля devel) и другие. Привычная отладка с помощью xdebug в файлах twig шаблонов тоже недоступна. Во-вторых, шаблоны Twig компилируются в php файлы, которые кешируются в файловой системе (в Drupal 8 файлы хранятся в каталоге sites/default/files/php/twig). И после установки Drupal 8 отладочные функции twig будут недоступны, также вы не увидите изменений сделанных в шаблоне до очистки кеша (кеш в Drupal 8 с помощью drush чистится командой drush cr).

Как включить отладку шаблонов

Для включения возможности отладки выполните следующие действия:

  • найдите файл services.yml, который обычно размещен в sites/default/services.yml;
  • если файл sites/default/services.yml не существует, просто скопируйте файл sites/default/default.services.yml в sites/default/services.yml;
  • далее нужно будет отредактировать файл sites/default/services.yml и отметить в нем нужные опции для отладки шаблонов.

Если используете Drupal Console, то отладочный режим для twig шаблонов можно включить одной командой:


drupal site:mod dev

Отладочные опции Twig:


# sites/default/services.yml

parameters:
  twig.config:
    debug: true 
    # Twig debugging

Какие возможности дает включенная опция debug в значение true в sites/default/services.yml?

Во-первых, в исходном html коде страницы все части кода будут обернуты в комментарии с информацией о используемых для вывода шаблонах и всех возможных вариантах именования файлов шаблонов (template suggestions).

twig debugging

Во-вторых, в шаблонах Twig появится возможность использования функцию dump() для вывода отладочной информации о переменных шаблона.
В-третьих, все файлы шаблона будут автоматически перекомпилироваться после любого изменения, внесенного в файл шаблона (смотри опцию auto_reload ниже).
По умолчанию опция установлена в false.

Twig auto-reload


auto_reload: true

Опция auto_reload установленная в true делает возможным перекомпиляцию twig шаблонов при каждом внесении в них изменений.
По умолчанию опция установлена в null.

Twig cache


cache: false

По умолчанию все twig шаблоны после компиляции кешируются и хранятся в файловой системе для улучшения производительности. Файлы перекомпилируются только после очистки кеша. Опция cache установленная в false позволит перекомпилировать шаблоны при каждом их использовании темой. В большинстве случаев лучше использовать auto_reload, так как шаблоны будут перекомпилироваться только после внесения в них изменений.
По умолчанию опция установлена в true.

Drupal render cache

По умолчанию в Drupal для улучшения производительности кешируется рендеринг для блоков и сущностей. Поэтому любые изменения, внесенные в шаблоне, не будут видны до очистки кеша. Для отключения render кеша и dynamic_page_cache нужно:
в файле settings.php раскомментировать следующие строки:


if (file_exists(__DIR__ . '/settings.local.php')) {
  include __DIR__ . '/settings.local.php';
}

Далее нужно скопировать файл sites/example.settings.local.php в sites/default/settings.local.php и в нем раскомментировать две строки (и не забыть очистить кеш):


$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Функция kint()

Кроме использования twig функции dump(), которую добавляет сам Twig, можно пользоваться функцией kint(), которую добавляет devel kint - подмодуль devel. Многие наверняка для отладки переменных в Drupal 7 использовали devel функцию dpm(), которая при выводе использует krumo. Так вот, kint является этаким krumo-заменителем. Kint, в отличие от krumo, при выводе объектов добавляет информацию о всех его методах.
Примеры использования kint() в шаблонах twig:


{{ kint(user) }}

twig kint

Можно вывести информацию сразу о нескольких переменных :


{{ kint(user, tags) }}

Если не передавать в функцию аргументы, выведется информация о всех переменных шаблона:


{{ kint() }}

При переносе сайта из dev окружения в production рекомендуется:

  • все опции в файле sites/default/services.yml вернуть в значения по умолчанию
  • для пользователей Drupal Console выполнить команду:
    
    drupal site:mod prod
    
    
  • в файле settings.php закомментировать строки:
    
    if (file_exists(__DIR__ . '/settings.local.php')) {
      include __DIR__ . '/settings.local.php';
    }
    
    

При написании статьи использована официальная документация Debugging compiled Twig templates