Автоматизированная миграция на Grav 2.0¶

Плагин Migrate to Grav 2.0 — рекомендуемый способ перехода с Grav 1.7 или 1.8 на Grav 2.0. Он устанавливается на существующий сайт 1.x, загружает свежую сборку Grav 2.0 и передаёт управление отдельному браузерному мастеру, который выполняет остальную миграцию в чистом процессе PHP без загруженного кода Grav 1.x.

Примечание

Сам плагин делает очень мало. Его единственная задача — передача управления: скачать zip-архив 2.0, подготовить его рядом с действующим сайтом, положить в webroot самодостаточный migrate.php и перенаправить вас на него. Всё рискованное происходит в мастере, который работает полностью вне Grav 1.x.

Предварительные требования¶

Grav 1.7.50+ или 1.8.x
Права на запись в webroot и папку tmp/
PHP 7.3.6+ для запуска самого старта (минимум Grav 1.x)
PHP 8.3+, доступный для мастера 2.0 (именно это требует Grav 2.0; он не обязан пока быть активным PHP для CLI или веб-сервера, но мастер откажется продолжать на любой более старой версии)

Важно

Если ваш хостинг предлагает только PHP ниже 8.3, не начинайте миграцию, пока не появится способ переключиться. Большинство хостингов с общим доступом позволяют менять версию PHP для домена в панели управления.

Шаг 1. Создайте резервную копию сайта¶

Перед началом сделайте полную резервную копию существующего сайта. Варианты:

Воспользуйтесь встроенным инструментом резервного копирования Grav: Админка → Инструменты → Резервная копия или bin/grav backup из CLI.
Либо скопируйте user/, backup/ и logs/ вручную, если так удобнее.

Мастер также создаст собственный zip-архив резервной копии на последнем шаге переключения (см. Решение проблем), но независимая резервная копия до начала — хорошая практика.

Шаг 2. Установите плагин¶

Через GPM:

bin/gpm install migrate-grav

Или через админку: Плагины → Добавить → Migrate to Grav 2.0 → Установить.

После установки в боковой панели админки появится новый пункт Migrate to Grav 2.0.

Шаг 3. Подготовьте миграцию¶

Запустить подготовку можно из админки или из CLI.

Из админки¶

Нажмите Migrate to Grav 2.0 в боковой панели.
Просмотрите панель требований. Всё, что не выполнено, помечено понятным объяснением.
Нажмите кнопку Начать миграцию.
Плагин скачает последнюю сборку Grav 2.0, распакует её в grav-2/ рядом с действующей установкой, скопирует мастер в /migrate.php в вашем webroot и перенаправит туда браузер.

Из CLI¶

bin/plugin migrate-grav init

Команда выводит следующий шаг, включая URL для открытия мастера. С этого момента всё происходит в мастере.

bin/plugin migrate-grav status

Показывает текущее состояние миграции: подготовлена, распакована, плагины проверены, учётные записи импортированы, контент импортирован, ожидает проверки или переключена.

Шаг 4. Пройдите мастер¶

Мастер — это многошаговый браузерный интерфейс, обслуживаемый отдельным migrate.php. Каждый шаг записывает результат в файл состояния .migrating в webroot, поэтому мастер можно безопасно перезагрузить, продолжить или перезапустить в любой момент без потери прогресса.

Шаги:

Извлечение¶

Скачанный zip-архив распаковывается в папку подготовки grav-2/, а лишний префикс grav-admin/ из архива отбрасывается.

Плагины и темы¶

Для каждого плагина и темы, установленных на сайте 1.x, мастер:

Читает файл blueprints.yaml пакета
Проверяет флаг compatibility: на наличие 2.0
Если флага нет, делает вывод по массиву dependencies:
Загружает метаданные каталога с getgrav.org (используя поддерживаемый вручную список совместимости _all как дополнительный ориентир в неоднозначных случаях)

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

Параметр	Варианты	Действие
Режим	`strict` (по умолчанию) / `permissive`	`strict` доверяет заявленным флагам. `permissive` переводит пакеты, признанные несовместимыми по выводу, в «совместимые», чтобы вы могли проверить их на подготовленном сайте 2.0, даже если авторы официально не пометили их.
Политика	`skip` (по умолчанию) / `disable`	Что делать с несовместимыми пакетами. `skip` удаляет пакет из подготовленной установки. `disable` оставляет файлы на месте, но записывает в конфигурацию запись, отключающую плагин в 2.0.

Затем совместимые пакеты заново устанавливаются в подготовленную копию из GPM в последней версии, готовой для 2.0.

Совет

Если вы не узнаёте некоторые помеченные здесь плагины, это хороший момент для уборки. Для всего, что вы больше не используете, подходящая политика — skip.

Учётные записи¶

Учётные записи пользователей, роли и разрешения копируются из user/accounts/ в подготовленную копию.

Контент¶

Следующие папки копируются с сайта 1.x в подготовленную установку 2.0:

user/pages/: весь контент страниц (не изменился между 1.7 и 2.0)
user/config/: системная конфигурация и конфигурация сайта (устаревшие ключи помечаются с предложенными заменами)
user/data/: отправленные формы, данные входа и всё, что плагины здесь хранят
user/env/: переопределения для конкретного окружения
user/languages/: переводы уровня сайта

Проверка¶

Мастер приостанавливается и просит проверить подготовленный сайт 2.0. Подготовленная копия доступна по адресу /grav-2/ относительно вашего действующего webroot, поэтому вы можете просматривать её параллельно с неизменённым сайтом 1.x.

Важно

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

Что стоит проверить перед продолжением:

Главная страница и репрезентативная выборка внутренних страниц отображаются корректно
Вход в админку работает с существующими учётными данными
Настроенные плагины загружаются без ошибок
Активная тема отображается корректно (или заменена на Quark 2, если для вашей старой темы ещё нет версии, совместимой с 2.0)
Страницы, которые использовали Twig в контенте ({{ ... }} или {% ... %} в теле страницы), по-прежнему отображаются как задумано. В 2.0 эта фича по умолчанию отключена, поэтому такие страницы показывают необработанный Twig, пока вы её не включите. Отчёт Инструменты → Отчёты → Twig в контенте помечает каждую затронутую страницу. Как включить фичу и какие есть более безопасные альтернативы, см. в разделе Twig в контенте.

Переключение¶

Это единственный шаг, на котором мастер затрагивает ваш действующий webroot. Он выполняется в три фазы:

Резервная копия. Каждый файл в действующей установке 1.x (кроме подготовленной grav-2/) упаковывается в grav-2/backup/migration-backup-<version>--<timestamp>.zip. После переключения архив оказывается в backup/<…>.zip рядом с другими резервными копиями Grav.
Удаление. Элементы верхнего уровня в webroot удаляются.
Переключение. Содержимое grav-2/ перемещается в webroot.

Когда мастер сообщает об успехе, ваш сайт 2.0 становится рабочим. Zip-архив резервной копии миграции сохраняется рядом со стандартными резервными копиями Grav, чтобы вы могли выполнить откат, если что-то было упущено.

Что делать, если шаг переключения прервался на середине, см. в разделе Решение проблем.

Шаг 5. Удалите плагин¶

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

bin/gpm uninstall migrate-grav

Или удалите его из списка Плагины в админке.

Отмена до переключения¶

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

.migrating в webroot
Подготовленную подпапку (по умолчанию grav-2/)
tmp/grav-2.0-staged.zip

Ваш существующий сайт Grav 1.x останется нетронутым.

Справочник по конфигурации¶

Значения по умолчанию подходят почти для любого сайта. Настраиваемые параметры находятся в user/config/plugins/migrate-grav.yaml:

enabled: true
source_url: 'https://getgrav.org/download/core/grav-update/latest'
source_local_zip: ''        # абсолютный путь к локальному zip-архиву 2.0 (только для разработки)
stage_dir: 'grav-2'
require_super_admin: true

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