Понимание хуков обновлений и пост-обновлений для успешных обновлений сайта Drupal

Во время обновлений ядра или модулей крайне важно обеспечить стабильность и целостность вашего веб-сайта Drupal. К счастью, модуль Update API и хуки Update/Post Update здесь, чтобы помочь.

Модуль Update API предоставляет хуки, необходимые для обновления кода и модулей на вашем сайте Drupal. Эти хуки — не что иное, как хуки Update и Post-Update, которые позволяют разработчикам настраивать обновления в соответствии со своими потребностями.

В этой статье мы обсудим API обновлений, что такое хуки обновления и пост-обновления, а также когда и как их следует использовать. Поняв оба типа хуков, вы сможете успешно обновлять свой сайт на Drupal с минимальными усилиями. Давайте начнем!

API обновления

При работе с существующим сайтом при обновлении кода в модуле может потребоваться обновить сохраненные данные, чтобы сохраненные данные были совместимы с новым кодом. Возможно, вы заметили, что перед вами мигают такие ошибки, как «На веб-сайте произошла непредвиденная ошибка». Страшно правда!? Я знаю! Здесь нам на помощь приходит API обновлений Drupal.

Если обновление происходит между двумя младшими версиями вашего модуля в одной и той же основной версии ядра Drupal, вы можете использовать Update API для обновления данных. Update API позволяет вам предоставить код, который выполняет обновление сохраненных данных всякий раз, когда ваш модуль вносит изменения в свою модель данных. Изменение модели данных относится к любому изменению, которое делает сохраненные данные на существующем сайте несовместимыми с обновленной кодовой базой этого сайта. Эти изменения модели данных включают:

Обновление схемы конфигурации

• Добавление/удаление/переименование конфигурационного ключа.
• Изменение типа данных конфигурационного ключа.
• Изменение ожидаемого значения по умолчанию для конфигурационного ключа и т. д.

Обновление схемы базы данных

• Добавление/изменение/удаление таблицы или поля базы данных.
• Перемещение сохраненных данных в другое поле или таблицу.
• Изменение формата сохраняемых данных и т. д.

Обновление сущностей и полей

• Добавление нового базового поля к существующему типу сущности.
• Обновление поля из устаревшего типа в новый тип и т. д.

Обновление данных

• Манипулировать сохраненными данными на существующем сайте.

Работа с хуками обновления

Хук hook_update_N() используется для введения обновления между младшими версиями модуля. Эти хуки размещаются внутри вашего модуля в файле *.install .

hook_update_N() записывается в виде (имя модуля)_update_(номер). Здесь N состоит из:

• 1 или 2 цифры относятся к совместимости ядра Drupal (Drupal 8, 9, 10 и т. д.)
• Следующая 1 цифра соответствует основной версии вашего модуля.
• Последние 2 цифры для последовательного счета, начиная с 01

Пример:

example_update_9201(): Первое обновление для версий 9.x-2.x.
Где «пример» — это имя модуля, первая цифра относится к версии ядра Drupal «9», цифра «2» относится к основной версии модуля, а последние две цифры «01» указывают на первую функцию обновления, написанную для модуль «пример».

Числовая часть функции реализации ловушки (например, 9201 в приведенном выше примере) хранится в базе данных, чтобы отслеживать, какие обновления уже были выполнены. Таким образом, вы никогда не должны перенумеровывать функции обновления.
Чтобы узнать текущую версию схемы модуля «пример, хранящийся в базе данных», используйте:

drush php-eval "echo drupal_get_installed_schema_version('пример');"

Чтобы вручную установить текущую версию схемы модуля «пример» обратно на «9201», используйте:

drush php-eval "echo drupal_set_installed_schema_version('пример', '9201');"

Примечание. Старайтесь избегать использования функции drupal_set_installed_schema_version() на рабочих сайтах, поскольку она напрямую обновляет вашу базу данных. Вы можете использовать его в своей локальной или более низкой тестовой среде во время разработки, чтобы сбросить версию схемы.

Добавьте правильное описание в комментарий к блоку документа перед функцией перехватчика обновления, так как оно будет напечатано для пользователей во время его запуска.

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

Эти хуки выполняются в отсортированном порядке, т. е. хук example_update_9201() выполняется перед example_update_9202(), следующим является 9203, 9204 и так далее.

Вы также можете изменить порядок сортировки этих хуков, введя зависимости между хуками. Используйте хук hook_update_dependencies() для запуска обновлений между двумя хуками обновления.

Все хуки обновления выполняются в пакетном режиме, а также поддерживают пакетную обработку элементов. Все хуки обновления имеют доступ к параметру $sandbox, который можно использовать для создания пакетных процессов в хуках обновления, чтобы обрабатывать огромные данные сразу, не вызывая истечения времени ожидания PHP.

Простой пример хука обновления для добавления нового конфигурационного ключа:

На данный момент файл example_module.settings.yml содержит:

Чтобы добавить новое описание ключа в конфигурацию:

• Добавьте ключ «описание» в файл настроек

• Добавьте update_hook в файл example_module.install:

• Используйте drush updb для запуска хука.

• Проверьте обновленную конфигурацию, обновлено описание нового ключа.

Работа с хуками Post Update

Хук hook_post_update_NAME(), аналогичный хуку обновления, используется для введения обновления. Но этот хук в основном предназначен для обновления данных, например сущностей. Эти хуки выполняются после запуска всех хуков hook_update_N(). На данном этапе Drupal уже полностью отремонтирован, поэтому вы можете использовать любой API внутри сайта.

Эти хуки размещаются в файле *.post_update.php в вашем модуле.

hook_post_update_NAME() записывается в виде (имя модуля)_post_update_(любое имя). Здесь NAME может быть любым произвольным именем машины. Это буквенно-цифровое наименование функций в файле — единственное, что обеспечивает порядок выполнения этого хука.

Как и в случае с хуками обновления, добавьте правильное описание в комментарий docblock перед хуком post_update. Кроме того, не используйте повторно одно и то же имя хука.

Структура hook_post_update_NAME():

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

Как и в случае с перехватчиками обновления, используйте параметр $sandbox, чтобы указать, что пакетный API следует использовать для перехватчиков post_update.

Простой пример использования хука post-update для обновления данных термина:

• В настоящее время все термины в словаре тегов имеют отключенное поле «Тестовый пример».

• Добавьте хук post_update в файл example_module.post_update.php, чтобы включить поле «Тестовый пример» для всех существующих терминов.

• Используйте drush updb для запуска хука.

• Проверьте обновленные данные термина, флажок «Тестовый пример» должен быть включен.

Как запустить эти крючки!

Вы можете использовать команду Drush для выполнения этих ловушек, drush updb. Он создает пакет в следующие шаги:

• Обнаружены все хуки обновления.
• Разрешает зависимость и сортирует их порядок.
• Крючки расставлены для пакетной обработки.
• Далее обнаруживаются все хуки Post.
• Если есть хуки post_update и если update_hook запускался ранее, то кеши очищаются.
• Затем вставьте каждый хук post_update в пакет.
• Выполнить партию.

Одним из основных преимуществ хука после обновления по сравнению с хуком обновления является то, что Drupal полностью функционален во время запуска постобновления. Это позволяет разработчикам использовать любые службы Drupal при использовании хука после обновления. При использовании хука обновления нельзя предполагать, что Drupal полностью восстановлен, и избегать использования других хуков, API-интерфейсов сущностей и т. д.

Последние мысли

При попытке исправить ваш сайт путем обновления схемы конфигурации/базы данных попробуйте использовать перехватчики обновлений. Когда дело доходит до манипулирования сохраненными данными, повторного сохранения конфигураций, обновления объектов контента, очистки кеша и т. д., то более целесообразно использовать перехватчики после обновления.

Честно говоря, на Drupal.org нет четкой документации о том, когда какой хук использовать! Существует открытый вопрос с просьбой улучшить документацию по использованию этих двух хуков, в которую вы можете внести свой вклад, если хотите.

Но, основываясь на опыте разработчиков и рассматривая в качестве примера основные модули Drupal 9 и 10, используйте перехватчики обновления для выполнения операций CRUD с конфигурациями или базами данных (т.е. восстановление сайта) и используйте перехватчики после обновления для сущностей содержимого CRUD ( затем исправить данные на обновленном сайте), так как хуки после обновления запускаются после хуков обновления.

Понравилось читать эту статью? Подарите нам немного любви и подпишитесь на нашу еженедельную рассылку сегодня!