Перейти к содержанию

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

Разработка версии 1.8 продолжается, содержимое может не соответствовать последним выпущенным версиям Grav 1.7 или бета-версии 1.8

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

  • Требуется PHP 8.3+ — серьёзное повышение минимальной версии с PHP 7.3 в Grav 1.7
  • Безопасная система обновлений — комплексные предварительные проверки, staging-среда, валидация и возможность отката
  • Улучшенная поддержка 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

Grav 1.8 требует PHP 8.3 или более новую версию. Это серьёзное изменение по сравнению с требованием PHP 7.3.6+ в Grav 1.7. Обязательно создайте резервную копию сайта и протестируйте обновление в тестовой среде перед обновлением рабочего сайта. Либо используйте режим «safe-upgrade» — он автоматически создаёт восстанавливаемый снимок ядра Grav.

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

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

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

    • Проверьте объявления параметров с nullable-типами
    • Обновите использование динамических свойств
    • Замените устаревшие функции
  2. Ошибки драйвера кэша⚓︎

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

    • Grav 1.8 автоматически преобразует адаптеры Doctrine Cache (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 Logging⚓︎

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

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

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

  5. Отсутствующая настройка⚓︎

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

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

Grav 1.8 требует PHP 8.3 или новее. Рекомендуется использовать последнюю версию PHP 8.4.

Критические изменения, ломающие совместимость⚓︎

Требования к версии 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 представляет комплексную систему безопасного обновления:

Предварительные проверки (Preflight Checks)⚓︎

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

bin/grav preflight

Команда preflight проверяет:

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

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

Новая система обновления включает:

  • Staging — создание снимков состояния до начала обновления
  • Validation — проверка целостности после обновления
  • Rollback — автоматический откат в случае сбоя обновления

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

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

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

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

Ручное обновление Twig до версии 3⚓︎

Переключатели совместимости автоматически переписывают небольшое количество конструкций Twig 1/2 «на лету», но рекомендуется обновить шаблоны окончательно, чтобы избежать трансформаций во время выполнения.

  • Защита циклов (loop guards): замените устаревшие циклы for с проверками внутри на предварительную фильтрацию коллекции с помощью встроенного условия if ({% for page in collection if page.published %}): 
    {# Legacy #}
{% for page in collection if page.published %}
    {{ page.title }}
{% endfor %}

{# Twig 3 friendly #}
{% for page in collection|filter(page => page.published) %}
    {{ page.title }}
{% endfor %}
  • блоки spaceless и filter: В Twig 3 удалены блоки {% spaceless %} и {% filter %} — замените их на {% apply %}. 
    {# Legacy #}
{% 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 в классах фреймворка
  • Исправления совместимости с 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. Тестируйте в staging-среде — никогда не обновляйте продакшн напрямую

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

Способ 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. Перейдите по адресу /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) при безопасном обновлении могли пропадать файлы с точкой в начале имени (dotfiles). Если вы обновлялись на этих сборках, обязательно проверьте корень проекта на наличие файлов вроде .htaccess и, если что-то отсутствует, выполните повторное безопасное обновление последней версией.
  • Права на CLI-скрипты: В 1.8.0-beta.16 исправлено восстановление прав на выполнение скриптов bin/* после обновления. Если CLI-утилиты перестали запускаться («permission denied»), выполните chmod +x bin/*.
  • Изменения в YamlUpdater API: В версиях 1.8.0-beta.5 — beta.7 добавлены публичные методы YamlUpdater::get(), set() и exists(). Если у вас есть автоматизация или плагины, работающие с обновлением YAML, переключитесь на эти методы вместо использования приватных внутренних механизмов.

Где получить помощь⚓︎

Полезные ресурсы⚓︎

Информация для сообщений об ошибках⚓︎

При обращении за помощью укажите:

  • Версию PHP
  • Версию Grav (до и после обновления)
  • Вывод команды preflight
  • Логи ошибок
  • Список установленных плагинов

Миграция из среды разработки⚓︎

Если обновляете сайт разработки:

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

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