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

Начиная с Grav 2.0, плагины и темы могут объявлять, с какими мажорными версиями Grav они совместимы, используя свойство compatibility: в blueprints.yaml. Это объявление читает мастер Migrate to Grav 2.0 при переносе существующих сайтов 1.x, а также GPM при установке или обновлении пакетов на сайте 2.0.

Проблема¶

Крупное обновление Grav (например, 1.7 → 2.0) может добавить требования к версии PHP, изменения API или внутренний рефакторинг, которые ломают плагины. Существующее свойство dependencies: объявляет только минимальные требования; оно не может выразить «этот плагин протестирован и подтверждённо работает на Grav 2.0».

Свойство compatibility:¶

Добавьте раздел compatibility: в blueprints.yaml плагина или темы:

name: My Plugin
slug: my-plugin
type: plugin
version: 2.1.0
description: A great plugin
dependencies:
  - { name: grav, version: '>=1.7.0' }

compatibility:
  grav:
    - '1.7'
    - '2.0'

Ключ grav: содержит список версий Grav в формате major.minor, на которых протестировано расширение. Используются только версии major.minor (например, 1.7, 2.0); патч-версии здесь не важны.

Свойство вложено в ключ верхнего уровня compatibility:, чтобы обеспечить будущее расширение (например, php: для совместимости с версией PHP).

Как это работает¶

Флаг совместимости читается в двух разных точках: во время миграции с 1.x на 2.0 и во время установки/обновления плагинов на сайте 2.0.

Во время миграции с 1.x на 2.0¶

Плагин Migrate to Grav 2.0 проверяет совместимость каждого установленного плагина и темы на этапе шага 2 (Copy & Migrate) мастера. Для каждого пакета мастер:

1. Читает свойство compatibility: из blueprints.yaml пакета
2. Если свойство не задано, переходит к выводу (см. ниже)
3. Сравнивает с целевой версией Grav 2.0
4. Для пакетов, совместимых с 2.0, запускает GPM, чтобы получить последний релиз, готовый к 2.0
5. Для несовместимых пакетов применяет политику плагинов, выбранную пользователем: Пропустить удаляет пакет из подготовленной установки, Отключить оставляет файлы на месте, но записывает запись конфигурации, отключающую плагин в 2.0

Пользователь также выбирает между строгим и разрешающим режимами совместимости:

• Строгий доверяет флагам, как они объявлены
• Разрешающий повышает выведенные несовместимые пакеты до «совместимых», чтобы пользователь мог проверить их на подготовленном сайте 2.0, даже если их авторы ещё официально не отметили их

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

Миграция выполняется в новой подготовленной установке, работающей параллельно. Действующий сайт 1.x пользователя остаётся нетронутым, пока он не решит выполнить повышение.

Во время установок GPM на сайте 2.0¶

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

Правила вывода¶

Если у плагина нет свойства compatibility:, Grav выводит совместимость из массива dependencies::

Это значит:

• Существующие плагины без свойства считаются совместимыми только с 1.7, что не даёт непротестированным плагинам работать на 2.0 после обновления.
• Новые плагины, написанные специально для 2.0 с зависимостью >=2.0.0, автоматически считаются совместимыми с 2.0.

Для авторов плагинов¶

Добавление совместимости¶

После тестирования плагина на новой версии Grav добавьте её в список compatibility.grav:

compatibility:
  grav:
    - '1.7'
    - '2.0'

Затем выпустите новую версию плагина. У пользователей, обновляющих плагин, будет объявление совместимости, и мастер миграции (или GPM на уже мигрированном сайте 2.0) примет его без перехода к политике пропуска или отключения.

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

Перед объявлением совместимости с 2.0 проверьте:

• Плагин устанавливается и включается без ошибок на Grav 2.0
• Вся основная функциональность работает как ожидается
• Нет предупреждений об устаревании PHP или ошибок с версией PHP, требуемой Grav 2.0
• Все зависимости Composer совместимы (особенно psr/log и monolog, если используются)
• Интеграция с админкой (схемы, формы) отображается корректно

Связь с зависимостями¶

compatibility: и dependencies: служат разным целям:

Плагин может зависеть от >=1.7.0 (ему нужна как минимум 1.7 для работы), объявляя совместимость и с 1.7, и с 2.0 (он протестирован на обеих). Проверка зависимостей гарантирует доступность нужных API; проверка совместимости — что плагин действительно проверен в работе.

Требование разных версий для разных поколений Grav¶

Плагину, поддерживающему и 1.7, и 2.0, часто нужна разная версия одной и той же зависимости для каждого. Поэтому запись зависимости может нести необязательный ключ grav:, указывающий поколение (или поколения), к которым она применяется, с тем же написанием, что и compatibility.grav:

1
2
3
4
5
6
7
8
9

dependencies:
  - { name: grav, version: '>=2.0.25' }
  - { name: form, version: '>=7.0.0', grav: '1.7' }
  - { name: form, version: '>=9.1.0', grav: '2.0' }
  - { name: api,  version: '>=1.0.24', grav: '2.0' }
  - { name: login, version: '>=3.9.0' }

compatibility:
  grav: ['1.7', '2.0']

На сайте Grav 2 это разрешается в form >=9.1.0, api >=1.0.24 и login >=3.9.0. На сайте Grav 1.7 — в form >=7.0.0 и login >=3.9.0, а требование api полностью пропускается.

Правила:

• Запись без ключа grav: применяется ко всем поколениям, поэтому каждая схема, написанная до этой фичи, ведёт себя точно как раньше.
• grav: принимает одно поколение ('2.0') или список (['1.7', '2.0']).
• Запись, указывающая поколение, которое не запущено, пропускается.
• Зависимость, нужная только для одного поколения, выражается просто отсутствием её для другого.
• Если у пакета есть и квалифицированная запись для текущего поколения, и неквалифицированная, квалифицированная запись выигрывает безоговорочно. Она не объединяется, потому что объединение сохраняет более высокую из двух версий и отбросило бы намеренно более низкое требование.

Если у вашего плагина сейчас вообще нет зависимости grav, добавьте её перед использованием квалифицированных записей; иначе ничто не помешает старой установке неправильно их прочитать.

Для администраторов сайта¶

Во время миграции на 2.0¶

При миграции с Grav 1.x на 2.0 через плагин Migrate to Grav 2.0 шаг 2 мастера покажет:

• Совместимые пакеты: сохранены и обновлены до последнего релиза, готового к 2.0, через GPM.
• Несовместимые пакеты: проходят через выбранную вами политику плагинов (Пропустить или Отключить).

Вы также выбираете между строгим и разрешающим режимами совместимости:

• Строгий — по умолчанию. Доверяет флагу compatibility: и правилам вывода как есть.
• Разрешающий повышает выведенные несовместимые пакеты до «совместимых», чтобы вы могли проверить их на подготовленном сайте 2.0, даже если их авторы ещё официально не отметили их. Явно указанные несовместимости всё равно блокируются в любом режиме.

Поскольку миграция выполняется как параллельная подготовленная установка, можно повторять попытки (сбросить, перезапустить, повторить шаг) и пробовать разные комбинации политик и режимов, не затрагивая действующий сайт 1.x.

После миграции¶

После того как подготовленный сайт 2.0 повышен и запущен:

1. Проверьте обновления версий плагинов, отключённых вашей политикой. Авторы могли выпустить версии с флагом 2.0 с момента миграции.
2. Обновите плагины через GPM: bin/gpm update
3. Включайте отключённые плагины по одному, проверяя корректность каждого
4. Если плагин вызывает проблемы, отключите его и свяжитесь с автором плагина