Обновление до Grav 1.6¶

Grav 1.6 — самое крупное обновление с момента первого выпуска Grav. В нём появилось несколько новых фич, улучшений и исправлений ошибок, а также множество архитектурных изменений, прокладывающих дорогу к Grav 2.0.

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

Вкладка устаревшего в панели отладки¶

Нам нужна вкладка Deprecated в панели отладки: она позволяет выявлять устаревшие вызовы и исправлять их или сообщать о них до обновления до более поздних версий Grav. Исправление проблем, найденных на вкладке Deprecated, поможет сделать сайт быстрее и сэкономит время при будущих обновлениях.

![Вкладка Deprecated](deprecated-tab.png?classes=shadow)

Чтобы поймать все проблемы, очистите кэш и запустите Grav с отключённым кэшированием — так больше шансов поймать все ошибки. Даже выполнив эти шаги, вы можете заметить, что некоторые ошибки YAML/Twig появляются только после очистки кэша.

Вкладка Deprecated содержит список найденных устаревших фич. Каждая проблема кликабельна и открывает сообщение об устаревании с кратким объяснением проблемы и трассировкой, позволяющей найти и исправить код. Справа виден тип устаревшей ошибки, а в правом нижнем углу можно фильтровать отображаемые типы, нажимая на бейджи.

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

Есть несколько типов устаревших проблем:

• yaml: YAML- или Markdown-файл использует устаревший синтаксис YAML.
• twig: файл Twig содержит устаревший синтаксис Twig или возникла другая проблема, связанная с Twig.
• grav: что-то вызывает устаревший метод Grav или использует устаревшее свойство.
• vendor: что-то использует устаревший код сторонней библиотеки.
• unknown: неизвестное устаревшее сообщение.

Разбор YAML¶

Grav 1.6 использует парсер YAML из Symfony 4.2, который гораздо точнее следует стандарту YAML, чем предыдущий парсер из Symfony 3.4. Это значит, что YAML-файлы, которые раньше работали нормально, могут вызвать ошибки из-за недопустимого YAML. Однако если файл не загружается с новой версией парсера 4.2, Grav по умолчанию всё равно откатится к старой версии 3.4, чтобы сайт продолжал работать. Но это снизит производительность сайта, поэтому проблемы нужно находить и исправлять, чтобы обеспечить оптимальную производительность.

В Grav 1.6.7 и всех более поздних версиях есть новая команда CLI для обнаружения проблем разбора YAML: запустите bin/grav yamllinter, чтобы найти и исправить ошибки разбора YAML на сайте. Эту команду рекомендуется запускать сразу после обновления до Grav 1.6 или более поздней версии.

В Admin 1.9.3 и всех более поздних версиях YAML Linter встроен в Tools > Reports, если вы предпочитаете его команде CLI.

Ищите такие ошибки YAML:¶

• Не используйте @, \, |, % и > в начале строки без кавычек: не используйте @data-options: [], вместо этого используйте data-options@: [].
• Всегда добавляйте пробел после двоеточия : в ключах: не используйте key:value, используйте key: value.
• Всегда заключайте в кавычки null, true, false, 2.0 (числа с плавающей точкой) в ключах; ключи могут быть только целыми числами или строками.
• Также заключайте в кавычки null, true, false, 2 и 2.0 в значениях, если они должны быть строками.
• При заключении строк в двойные кавычки теперь нужно экранировать символы \.

Панель отладки тоже позволяет находить устаревший YAML. Просто откройте панель отладки и посмотрите вкладку Deprecated. Если вкладки нет, проблем не обнаружено.

Режим совместимости YAML¶

По умолчанию в Grav 1.6 режим совместимости YAML включён. Это позволяет старым сайтам продолжать работать после обновления, но не идеально для новых сайтов или если вы уже исправили и проверили сайт на все ошибки разбора YAML.

Изменить эту настройку можно в user/config/system.yaml:

1
2

strict_mode:
  yaml_compat: false

Мы рекомендуем пока не трогать эту настройку на существующих сайтах, а вместо этого создавать тестовые сайты с выключенным режимом совместимости. Кроме того, на любом новом сайте на Grav 1.6 или новее режим совместимости следует выключать во время разработки: это сэкономит много времени, когда придёт пора обновляться до Grav 2.0.

Twig¶

Отложенные блоки¶

Обновите тему до версии, которая поддерживает отложенные блоки ресурсов, чтобы обеспечить полную поддержку Grav 1.6. Если же у вас своя изменённая или разработанная тема, обновите её самостоятельно, чтобы она продолжала работать с новыми фичами и более поздними версиями Grav и его плагинов, следуя руководству из записи блога Important Theme Updates.

Устаревший Twig¶

Grav 2.0 будет использовать Twig 2 вместо Twig 1, который сейчас используется в выпусках Grav 1.x. В Twig 2 удалено несколько устаревших фич, поэтому нужно найти и исправить все эти проблемы до обновления до Grav 2.0.

Панель отладки позволяет находить устаревшие проблемы Twig. Просто откройте панель отладки и нажмите вкладку Deprecated.

Ищите такие проблемы Twig:¶

• Макросы, импортированные в файле, больше не будут доступны в дочерних шаблонах (например, через вызов include). Макросы нужно явно импортировать в каждом файле, где вы их используете.
• Фильтр |replace() будет работать только с ассоциативным массивом в качестве параметра: { "I like this and that."|replace({'this': 'foo', 'that': 'bar'}) }}.
• Тест sameas() теперь следует писать как same as().

Подробнее о том, что устарело, можно узнать здесь.

Автоэкранирование¶

Grav был довольно защищён от уязвимостей, кроме XSS-атак, которые можно вызвать без особых усилий в любом коде, не экранирующем должным образом недоверенный пользовательский ввод. Twig — простой способ писать шаблоны, но при этом слишком легко забыть, что большинство переменных, используемых в шаблонах, не очищаются перед использованием. Даже если они отфильтрованы и безопасны, они могут содержать специальные символы, которые нужно экранировать, чтобы HTML-код был валидным.

Например, у вас может быть такой шаблон Twig:

1
2
3
4

{% set my_string = '<script>echo("hello there!");<script>' %}
<p>
    {{ my_string }}
</p>

По умолчанию в Grav автоэкранирование Twig выключено ради простоты и ясности шаблонов, но, к сожалению, это было плохое решение, потому что никто, включая нас, не помнит, что нужно всегда экранировать переменные, которые могут содержать специальные символы или приходят из недоверенного источника. Хуже того, обычно неизвестно, безопасна ли переменная для HTML или нет. Чтобы сайт был защищён от большинства XSS-уязвимостей, включите автоэкранирование в конфигурации. К сожалению, темы и плагины, использующие шаблоны Twig, обычно не работают с включённой настройкой, а шаблоны, написанные без явного экранирования, скорее всего, уязвимы к вредоносному содержимому.

В примере выше, поскольку автоэкранирование отключено, вывод отрендерится как чистый HTML, и всплывёт окно с сообщением "hello there!". Однако это следует экранировать фильтром Twig |e (или |e('html')):

1
2
3
4

{% set my_string = '<script>echo("hello there!");<script>' %}
<p>
    {{ my_string|e }}
</p>

Поскольку большинство людей склонны забывать экранировать переменные в Twig, а использование |e везде может сделать шаблоны менее читаемыми, в user/config/system.yaml появилась новая настройка:

1
2

strict_mode:
  twig_compat: false

Эта настройка принудительно включает auto-escaping во всех шаблонах Twig и отключает старую настройку для его включения и выключения. Побочный эффект: на сайте, вероятно, появится несколько экранированных фрагментов контента, которые нужно исправить, применив фильтр |raw ко всему контенту, который должен содержать HTML и только HTML. Многие шаблоны и плагины ещё не обновлены для работы с принудительным экранированием, поэтому сообщайте о любых ошибках в них, чтобы их можно было вовремя исправить.

Переход на автоэкранирование будет непростым. Во время перехода все шаблоны должны либо содержать оба фильтра, |e и |raw, на каждой переменной, чтобы шаблон был безопасен в обоих режимах, либо весь код шаблона можно обернуть тегами Twig {% autoescape %}.

Дополнительную информацию см. в руководстве по Twig.