Руководство по обновлению до Grav 1.6⚓︎

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

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

Вкладка Deprecated на панели отладки⚓︎

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

Чтобы убедиться, что вы поймали все проблемы, вам следует либо очистить кэш, либо запустить 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, интегрированный в Сервис > Отчёты, если вы предпочитаете использовать его вместо команды 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:

strict_mode:
  yaml_compat: false

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

Twig⚓︎

Отложенные блоки⚓︎

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

Устаревший 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:

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

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

В приведенном выше примере, поскольку автоматическое экранирование отключено, вывод будет отображаться как чистый HTML, и появится всплывающее окно с предупреждением «привет, там!». Однако этого следует избегать с помощью escape-фильтра Twig |e (или |e ('html'):

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

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

strict_mode:
  twig_compat: false

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

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

См. Руководство по Twig для получения дополнительной информации.