Обновление до Grav 1.8 beta¶

Grav 1.8 приносит значительные улучшения: требование PHP 8.3, обновлённые зависимости и новую систему безопасного обновления. Вот несколько главных новшеств:

• Требование PHP 8.3+: серьёзное изменение по сравнению с требованием PHP 7.3 в Grav 1.7
• Система безопасного обновления: комплексные предварительные проверки, подготовка, валидация и возможность отката
• Улучшенная поддержка Twig: обновление до Twig 3.x (форк для совместимости с Defer)
• Интеграция с Symfony 7: компоненты обновлены до Symfony 7.x для лучшей производительности и безопасности
• Улучшенное кэширование: провайдер Symfony Cache заменяет Doctrine Cache (устаревший)
• Совместимость с Monolog: переход на Monolog 3, но сохранена поддержка синтаксиса Monolog 2.3+
• Качество кода: поддержка PHPStan уровня 6 и исправления для совместимости с PHP 8.4

Самые частые проблемы¶

1. Проблемы совместимости с PHP 8.3¶

   Проблема: пользовательские плагины и темы, использующие устаревшие фичи PHP, перестают работать Решение: обновите код для совместимости с PHP 8.3

   • Проверьте объявления параметров, допускающих null
   • Обновите использование динамических свойств
   • Замените устаревшие функции

2. Ошибки драйверов кэша¶

   Проблема: сайт ломается после обновления из-за удалённых драйверов кэша Решение:

   • Grav 1.8 автоматически сопоставляет адаптеры кэша Doctrine (apcu, memcached, redis, array и т. д.) с их эквивалентами в Symfony Cache при обновлении.
   • Если Grav встречает адаптер, который не может сопоставить, он откатывается к кэшу filesystem по умолчанию, чтобы сайт продолжал работать.
   • Для ясности обновите конфигурацию кэша в system.yaml до нужного адаптера:

     system:
       cache:
         driver: apcu  # вместо apc
         # или
         driver: memcached  # вместо memcache
     

3. Проблемы журналирования Monolog¶

   Проблема: пользовательский код журналирования может сломаться с Monolog 2.3/3.x Решение: обновите вызовы журналирования:

   // Старый вариант
   $this->grav['log']->addInfo($message);
   $this->grav['log']->addError($message);
   ...
   
   // Новый вариант (совместим и с Monolog 2.x, и с 3.x)
   $this->grav['log']->info($message);
   $this->grav['log']->error($message);
   ...
   

4. Конфликты журналирования PSR-3¶

   Проблема: плагины или темы, которые поставляются с собственной папкой vendor/ или composer.json и фиксируют psr/log на старой версии 1.x, вынуждают Composer установить несовместимую версию. Это ломает ожидания обработчика Monolog 3 в Grav и вызывает ошибки вида Return type must be compatible with Psr\Log\LoggerInterface. Решение:

   • Удалите явное требование psr/log из своего расширения либо
   • Предпочитайте версию из комплекта Grav, добавив в composer.json блок replace:

     "replace": {
         "psr/log": "*"
     }
     

   • Удалите папку vendor/ плагина после обновления composer.json и пересоберите её командой composer install.

   Команда bin/gpm preflight показывает эту проблему в предупреждениях PSR/log compatibility, устраните их до обновления.

5. Отсутствующая настройка конфигурации¶

   Проблема: ошибки из-за удалённой настройки system.umask_fix Решение: удалите эту настройку из system.yaml, так как она удалена по соображениям безопасности

Краткое руководство по обновлению¶

Критические нарушения совместимости¶

Требование к версии PHP¶

• Минимальный PHP: 8.3+ (в Grav 1.7 было 7.3.6+)
• Убедитесь, что ваше хостинговое окружение поддерживает PHP 8.3 или выше
• Обновите устаревший PHP-код в пользовательских плагинах и темах

Удалённые драйверы кэша¶

Следующие неподдерживаемые драйверы кэша удалены. Поддерживаемые адаптеры (APCu, Memcached, Redis, Array, Filesystem и т. д.) обрабатываются Symfony Cache под теми же именами, а Grav откатывается к filesystem, если не может разрешить пользовательский адаптер: - APC (используйте apcu) - WinCache - XCache - Memcache (используйте memcached)

Удалённые настройки¶

• Настройка system.umask_fix удалена по соображениям безопасности

Система безопасного обновления¶

Grav 1.8 представляет комплексную систему безопасного обновления:

Предварительные проверки¶

Запустите проверки совместимости перед обновлением:

bin/grav preflight

Команда preflight проверяет: - Плагины, ожидающие обновления - Конфликты журналирования PSR-3 - Конфликты версий Monolog - Другие проблемы совместимости

Автоматические безопасные обновления¶

Новая система обновления включает: - Подготовку: создаёт снимки перед обновлением - Валидацию: проверяет целостность обновления - Откат: автоматическое восстановление, если обновление не удалось

Режим восстановления¶

• Интерфейс восстановления, доступный по токену
• Система карантина плагинов
• Поддержка отката из CLI

Улучшенная поддержка Twig¶

• Обновление до Twig 3.x (форк для совместимости с PHP 8.4)
• Новые настройки strict_mode.twig2_compat и strict_mode.twig3_compat
• Поддержка Deferred Extension для совместимости с Twig 1.x
• Улучшения безопасности песочницы Twig

Ручное обновление до Twig 3¶

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

• Защита в циклах: замените устаревшие циклы for со встроенными условиями if ({% for page in collection if page.published %}), сначала отфильтровав последовательность.

  {# Устаревший вариант #}
  {% for page in collection if page.published %}
      {{ page.title }}
  {% endfor %}
  
  {# Совместимо с Twig 3 #}
  {% for page in collection|filter(page => page.published) %}
      {{ page.title }}
  {% endfor %}
  

• Блоки spaceless и filter: в Twig 3 удалены блоки {% spaceless %} и {% filter %}; замените их на {% apply %}.

  {# Устаревший вариант #}
  {% spaceless %}
      <div>{{ content|raw }}</div>
  {% endspaceless %}
  
  {# Twig 3 #}
  {% apply spaceless %}
      <div>{{ content|raw }}</div>
  {% endapply %}
  

• Тест sameas: используйте is same as вместо is sameas.

  {% if theme is same as('my-theme') %}
  

• Сигнатура фильтра replace: Twig 3 ожидает карту вместо двух строковых аргументов.

  {{ title|replace({'_': ' '}) }}
  

После исправления шаблонов отключите system.strict_mode.twig2_compat и system.strict_mode.twig3_compat и очистите кэш, чтобы убедиться, что всё рендерится без слоя совместимости.

Интеграция с Symfony 7¶

• Компоненты обновлены до Symfony 7.x
• Провайдер Symfony Cache (заменяет Doctrine Cache)
• Лучшая производительность и безопасность

Обновление зависимостей¶

Основные зависимости¶

• PHP: 8.3+ (было 7.3.6+)
• Twig: 3.x (форк для совместимости с Defer)
• Symfony: 7.x (было 4.4)
• Monolog: 3.x (было 1.25)
• RocketTheme/Toolbox: 2.0 (было 1.0)

Удалённые зависимости¶

• Doctrine Cache (заменён на Symfony Cache)
• Устаревшие драйверы кэша (APC, WinCache, XCache, Memcache)

Изменения конфигурации¶

Новые настройки¶

system:
  strict_mode:
    twig2_compat: true    # включить режим совместимости с Twig 2
    twig3_compat: true    # включить режим совместимости с Twig 3

Обновлённые значения по умолчанию¶

• Драйверы кэша переведены на Symfony Cache
• Настройки безопасности ужесточены

Изменения для разработчиков¶

Улучшения качества кода¶

• Поддержка PHPStan уровня 6 в классах Framework
• Исправления для совместимости с PHP 8.4
• Улучшенные объявления типов
• Улучшенная обработка ошибок

Изменения API¶

• Обновлённая система событий
• Улучшенный интерфейс журналирования
• Улучшенные абстракции кэширования

Совместимость плагинов и тем¶

Обязательные обновления¶

• Плагины должны поддерживать PHP 8.3+
• Обновите вызовы журналирования для совместимости с Monolog
• Замените устаревшие вызовы функций
• Проверьте работу с компонентами Symfony 6.4/7.x

Контрольный список проверки¶

• Плагин загружается без ошибок
• Интерфейс админки работает корректно
• Формы обрабатываются правильно
• Загрузка медиафайлов работает
• Кэширование работает как ожидается

Процесс обновления¶

Контрольный список перед обновлением¶

1. Сделайте резервную копию сайта — всегда создавайте резервную копию перед обновлением
2. Проверьте версию PHP — убедитесь, что доступен PHP 8.3+
3. Запустите предварительную проверку — bin/grav preflight
4. Обновите пользовательский код — исправьте проблемы совместимости с PHP 8.3
5. Проверьте на тестовом окружении — никогда не обновляйте продакшен напрямую

Способы обновления¶

Способ 1: безопасное обновление (рекомендуется)¶

# Выполнить безопасное обновление Grav
bin/gpm self-upgrade --safe

# Следить за возможными проблемами
bin/grav logviewer

Способ 2: старое ручное обновление с ручной резервной копией¶

# Сначала резервная копия
bin/grav backup

# Запустить ручные предварительные проверки
bin/gpm preflight

# Обновить все пакеты
bin/gpm update -f

# Обновить Grav старой системой обновления
bin/gpm self-upgrade --legacy

Шаги после обновления¶

1. Проверьте работоспособность сайта
2. Проверьте панель администрирования
3. Проверьте формы и взаимодействие с пользователями
4. Просмотрите журналы ошибок
5. Обновите конфигурации плагинов, если нужно

Устранение неполадок¶

Частые проблемы¶

Ошибки кэша после обновления¶

# Очистить весь кэш
bin/grav clear-cache --all

# Проверить конфигурацию кэша
cat user/config/system.yaml | grep -A 5 cache:

Проблемы журналирования¶

# Проверить права на папку журналов
ls -la logs/

# Проверить журналирование
bin/grav log --level=debug

Совместимость плагинов¶

# Вывести список всех плагинов
bin/plugin list

# Проверить обновления
bin/gpm update --list-only

Процедуры восстановления¶

Использование режима восстановления¶

1. Перейдите по URL /recovery с токеном восстановления
2. Поместите проблемные плагины в карантин
3. При необходимости откатитесь к предыдущей версии

Восстановление из CLI¶

# Восстановление с выбором из последних снимков
bin/restore

# Вывести список снимков
bin/restore list

# Откатиться к предыдущей версии из снимка
bin/restore apply <version>

# Справка по команде
bin/restore -h

# Получить состояние восстановления
bin/restore recovery status

# Сбросить состояние восстановления
bin/restore recovery clear

Дополнительные примечания к журналу изменений¶

• Снимки безопасного обновления: ранние беты Grav 1.8 (до 1.8.0-beta.10) могли пропускать точечные файлы при безопасном обновлении. Если вы обновлялись такими сборками, перепроверьте корень проекта на наличие файлов вроде .htaccess и заново запустите последнюю процедуру безопасного обновления, если чего-то не хватает.
• Права на скрипты CLI: исправление в 1.8.0-beta.16 восстанавливает права на выполнение скриптов bin/* после обновлений. Если инструменты CLI перестали работать (отказ в доступе), выполните chmod +x bin/*, чтобы привести их к ожидаемому состоянию.
• Изменения API YamlUpdater: в версиях с 1.8.0-beta.5 по beta.7 появились новые публичные помощники YamlUpdater::get(), set() и exists(). Обновите любую автоматизацию или плагины, которые работают с обновлением YAML, чтобы вызывать эти методы, а не полагаться на приватные внутренности.

Как получить помощь¶

Ресурсы¶

• Документация Grav
• Проблемы на GitHub
• Форумы сообщества

Сведения для поддержки¶

Сообщая о проблемах, указывайте: - версию PHP - версию Grav (до и после обновления) - вывод команды preflight - журналы ошибок - список установленных плагинов

Миграция с окружения разработки¶

Если вы обновляете сайт для разработки: 1. Обновите локальный PHP до 8.3+ 2. Обновите зависимости composer 3. Запустите автоматические тесты 4. Обновите конвейеры CI/CD 5. Разверните на тестовом окружении перед продакшеном

⚠️ Важно: всегда проверяйте обновления на тестовом окружении, прежде чем применять их в продакшене. Новая система безопасного обновления даёт возможность отката, но предотвратить проблему лучше, чем восстанавливаться после неё.