Руководство по обновлению Drupal 9 до Drupal 10

В этом руководстве вы узнаете, как подготовить сайт, созданный на Drupal 9, для обновления на Drupal 10, а затем обновить его.

¶Введение

Drupal 10.0.0 является практически идентичной копией Drupal 9.4.0, за исключением того, что в Drupal 10 удалён весь код который объявлен устаревшим за время поддержки Drupal 9.

Замена вызовов устаревшего API на новый API — является основной задачей при обновлении. Если вы уделяли достаточное внимание коду в процессе поддержки сайта на Drupal 9, обновление должно быть максимально простым, как если бы вы обновлялись на новый минорный релиз Drupal 9.

Обновление можно свести к двум основным этапам:

• Подготовка Drupal 9: На данном этапе необходимо будет привести в порядок сайт на Drupal 9. Для этого нужно обновить Drupal ядро до актуального состояния, все сторонние используемые модули, а также привести в порядок свои модули и темы оформления.
• Обновление до Drupal 10: На этом этапе будет производиться обновление зависимостей.

В данном руководстве расписаны все этапы, для того чтобы подготовить и обновить свой проект с Drupal 9 до Drupal 10.

¶Рекомендуемые инструменты

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

• PHPStorm — IDE для PHP, может помочь как с поиском, так и устранением проблем, необходимых для обновления.
• Upgrade Status — модуль для Drupal, который позволяет провести комплексную проверку на готовность проекта к обновлению. Данный модуль рекомендуется использовать в процессе подготовки к обновлению. Он устанавливается (composer require drupal/upgrade_status) исключительно при помощи Composer, в противном случае он не будет работать. Важно: данный модуль должен быть отключен перед обновлением и удалён после обновления.

¶Подготовка проекта к обновлению

В данном разделе описаны этапы, которые помогут вам подготовить сайт на Drupal 9 к последующему обновлению на Drupal 10.

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

¶Проверка системных требований

Прежде чем начать что-то делать с сайтом, убедитесь что ваш текущий боевой сервер соответствует системным требованиям Drupal 10.

Сводка:

• Минимальная версия PHP увеличена до 8.1.
• База данных должна поддерживать тип данных JSON.
• Если вы используете MySQL или Percona Server — минимальная версия 5.7.8.
• Если вы используете MariaDB — минимальная версия 10.3.7.
• Если вы используете PostgreSQL — минимальная версия 12 с включенным расширением pg_trgm.
• Если вы используете SQLite — минимальная версия 3.26.

¶С использованием Drupal

Для того чтобы узнать об имеющихся проблемах и потенциальной несовместимости с будущим релизом, вы можете обратиться к стандартной странице «Отчёт о состоянии», для этого:

• Перейдите на страницу: «Отчёты» → «Отчёт о состоянии»
• Убедитесь что разделы «Веб-сервер», «PHP» и «База данных» используют рекомендуемые или более свежие версии.
• Найдите проверку «Database support for JSON», она должна иметь значение «Available».

¶С использованием Upgrade Status

Для того чтобы узнать об имеющихся проблемах и потенциальной несовместимости с будущим релизом, вы можете использовать Upgrade Status, для этого:

• Перейдите на страницу: «Отчёты» → «Upgrade Status»
• Изучите все обнаруженные проблемы в разделе «Drupal core and hosting environment»

¶Обновление ядра Drupal 9

Перед обновлением вам потребуется актуальная версия Drupal 9. Минимальная версия, необходимая для обновления до Drupal 10 — Drupal 9.3.0 (#3261486 в Drupal 10.0.0).

Хоть Drupal и предоставляет возможность обновиться до Drupal 10, пропустив Drupal 9.4.0, настоятельно не рекомендуется так делать.

В Drupal 9.4.0 пометили часть API устаревшим, не обновившись до данной версии, вы узнаете об этом только когда ваш сайт упадёт с исключением на Drupal 10. Эти проблемы могут всплыть уже в ходе использования Drupal 10 на боевом сервере.

¶Подготовка собственных модулей и тем оформления

Если на вашем проекте есть собственные модули и/или темы оформления, то вам необходимо убедиться что они в актуальном состоянии и совместимы с Drupal 10.

¶Обновите свойство core_version_requirement

Прежде всего, вам необходимо обновить свойство core_version_requirement в *.info.yml файлах. На момент обновления он должен содержать как Drupal 9, так и Drupal 10:

core_version_requirement: ^9 || ^10

¶Удалите свойство core

Убедитесь, что *.info.yml файлах не используется свойство core. Его нужно удалить, в противном случае будет выброшено исключение.

¶Обновите PHP код

Самая главная задача — нужно найти все вызовы устаревшего API и обновить код чтобы он использовал новый API.

Например, ваш модуль использует функцию drupal_get_path(), которая объявлена устаревшей в Drupal 9.3.0. Данная функция удалена в Drupal 10, это означает, что ваш код, который использует эту функцию, перестанет работать.

Для того чтобы узнать что нужно делать в такой ситуации, в Drupal всегда имеются комментарии. Для этого вы должны открыть исходный код drupal_get_path() и в нём будет доступна вся информация.

/**
 * Returns the path to a system item (module, theme, etc.).
 *
 * @param $type
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
 * @param $name
 *   The name of the item for which the path is requested. Ignored for
 *   $type 'core'.
 *
 * @return string
 *   The path to the requested item or an empty string if the item is not found.
 *
 * @deprecated in drupal:9.3.0 and is removed from drupal:10.0.0. Use
 *   \Drupal\Core\Extension\ExtensionPathResolver::getPath() instead.
 *
 * @see https://www.drupal.org/node/2940438
 * @see \Drupal\Core\Extension\ExtensionList::getPath()
 */
function drupal_get_path($type, $name) {
  @trigger_error('drupal_get_path() is deprecated in drupal:9.3.0 and is removed from drupal:10.0.0. Use \Drupal\Core\Extension\ExtensionPathResolver::getPath() instead. See https://www.drupal.org/node/2940438', E_USER_DEPRECATED);
  return dirname(drupal_get_filename($type, $name));
}

Из исходного кода функции становится ясно, что функция объявлена устаревшей в Drupal 9.3.0 и вместо неё необходимо использовать метод ExtensionPathResolver::getPath(). Для более детальной информации предоставлена ссылка с описанием этого изменения.

¶С использованием PHPStorm

В текущем разделе вы узнаете как найти код, который использует устаревший API при помощи IDE PHPStorm.

Для поиска вызова устаревших API при помощи PHPStorm следуйте следующим этапам:

• Запустите «Code» → «Analyze Code» → «Run Inspection by name» или SHIFT + SHIFT и начните вводить «Run inspection by name», а затем нажмите Enter.
• В появившемся окне «Enter inspection name:» введите «Deprecated», он будет в разделе PHP | General, затем нажмите Enter.
• В открывшемся модальном окне в разделе «Inspection Scope» выберите «Custom Scope» и выберите нужный Scope содержащий только ваш собственный код.
• Запустите анализ нажав на «OK».

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

¶С использованием Upgrade Status

В текущем разделе вы узнаете как найти код, который использует устаревший API при помощи модуля Upgrade Status.

• Перейдите на страницу: «Отчёты» → «Upgrade Status».
• На данной странице нас интересует раздел «Сканировать».
• В данном разделе выберете все собственные модули и темы оформления, а затем нажмите «Scan selected» внизу страницы.

Дождитесь окончания сканирования, после чего у вас откроется этот же отчёт, но уже с информацией по выбранным модулям и темам. Все модули и темы, которые содержат проблемы, будут добавлены в секцию «Fix manually».

По каждому модулю и теме будет предоставлена информация о найденных проблемах, вы можете нажать на ссылку «X problem(s)» чтобы получить больше информации.

В примере выше видно, что модуль example использует устаревшую функцию drupal_get_path(), а также информацию: в каком файле происходит вызов, на какой линии и как её исправлять.

Вам необходимо устранить все проблемы. Если вы считате что устранили все проблемы, или хотите провести проверку повторно, выделите желаемые модули и запустите сканирование повторно.

Если вы исправите все проблемы, модули попадут в раздел «Compatible with next major Drupal core version» — это означает что эти модули не содержат код и прочие проблемы, которые сломаются на Drupal 10.

¶Обновите Twig шаблоны

В Drupal 10, шаблонизатор Twig обновлён до 3 версии. Это означает, что устаревшие возможности Twig 1 будут больше недоступны, но устаревшие возможности Twig 2 продолжат работать.

Основные изменения и как обновлять шаблоны вы можете найти на странице обновления Drupal 10.0.0 (#3094493).

¶С использованием PHPStorm

В текущем разделе вы узнаете как найти Twig шаблоны, которые используют устаревший API при помощи IDE PHPStorm.

Для поиска проблемных шаблонов при помощи PHPStorm следуйте следующим этапам:

• Запустите: «Code» → «Analyze Code» → «Run Inspection by name» или SHIFT + SHIFT и начните вводить «Run inspection by name», а затем нажмите Enter.
• В появившемся окне «Enter inspection name:» введите «Deprecated Twig extension», он будет в разделе Symfony | Twig, затем нажмите Enter.
• В открывшемся модальном окне в разделе «Inspection Scope» выберите «Custom Scope» и выберите нужный Scope содержащий только ваш собственный код.
• Запустите анализ нажав на «OK».

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

¶С использованием Upgrade Status

В текущем разделе вы узнаете как найти Twig шаблоны, которые используют устаревшие возможности при помощи модуля Upgrade Status.

• Перейдите на страницу: «Отчёты» → «Upgrade Status».
• Выберете все собственные модули и темы оформления, а затем нажмите «Scan selected» внизу страницы.
• Дождитесь окончания сканирования.
• Исправьте все найденные проблемы с шаблонами.

В примере выше показано, что в шаблоне example.html.twig используется устаревший тег spaceless. Для решения проблемы необходимо заменить его использование одноимённым фильтром.

Пример исправления:

{# Было. #}
{% spaceless %}
  Старый синтаксис, не будет работать в Drupal 10.
{% endspaceless %}

{# Стало. #}
{% apply spaceless %}
  Новый синтаксис, будет без проблем работать в Drupal 10! Выполняет всё ту же функцию.
{% endapply %}

¶Обновление сторонних модулей и тем оформления

После того как вы подготовили ядро и собственный код, остаётся последний этап — подготовка сторонних модулей и тем оформления. Вам необходимо обновить все сторонние модули и темы оформления до актуальных версий, которые совместимы с Drupal 10.

Чем больше сторонних расширений вы используете, тем сложнее может оказаться данный этап. Поэтому рекомендуется оставить его напоследок, к тому моменту, когда вы до него дойдёте, возможно появятся решения и обновления для необходимых вас расширений.

В процессе сбора информации о тех или иных расширениях, вы можете столкнуться с проектами, у которых нет поддержки Drupal 10.

Что делать в данной ситуации? То что последний релиз не имеет поддержки Drupal 10, не означает что эту поддержку не добавили в dev версию модуля или работают над этим. В данной ситуации лучше всего перейти на страницу задач («All issues») проекта и изучить самые актуальные из них.

Если для проекта уже есть готовый патч с поддержкой Drupal 10, то у вас два варианта развития событий:

• Добавить данный патч в проект и обновить пакет, а затем просто дождаться когда патч будет уже в самом расширении, после чего удалить патч из проекта.
• Дождаться пока появится стабильный релиз с поддержкой Drupal 10.

Если для проекта отсутствует готовый патч с поддержкой Drupal 10, то стоит более детально изучить проект. Возможно он заброшен или автору проекта требуется помощь с подготовкой данного патча. Если вы не готовы самостоятельно добавить совместимость и поделиться с сообществом, вам остаётся только ждать. Заранее начните продумывать как вы замените это расширение, если для него так и не выйдет обновление с совместимостью.

¶Подготовка к обновлению

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

¶Поиск и обновление

В текущем разделе описано, как необходимо проверять сторонние расширения на совместимость с Drupal 10.

¶При помощи drupal.org

Для проверки совместимости модуля с Drupal 10 вы можете использовать официальный сайт Drupal — drupal.org.

Составьте список используемых расширений и посетите страницу каждого из расширений на drupal.org. Внизу страницы вы найдёте раздел «Releases» в котором содержится информация о текущих версиях проекта и его совместимости.

В примере выше, вы можете заметить раздел «Works with Drupal», в котором указано ^9.2 || ^10. Это означает что данный проект поддерживает Drupal 9.2.0 или новее, а также Drupal 10.

Если версия расширения на вашем проекте актуальная, вам ничего не нужно делать с данным расширением и можно идти дальше!

В текущем примере вы можете найти аналогичный раздел, но в нём уже совсем другая информация. Из него следует что модуль поддерживает Drupal 8.8.0 или новее, а также Drupal 9. Это означает, что текущий проект с версией 1.8 не заработает на Drupal 10.

¶При помощи Upgrade Status

Для того чтобы проверить расширения на совместимость с Drupal 10 вы также можете использовать Upgrade Status.

• Перейдите на страницу: «Отчёты» → «Upgrade Status».
• Выберите все сторонние модули и темы оформления, а затем нажмите «Scan selected» внизу страницы.

Проекты, которые совместимы с Drupal 10 окажутся в разделе «Compatible with next major Drupal core version»:

С такими проектами не нужно ничего делать, уже всё готово. Но некоторые проекты могут оказаться не готовы. Такие проекты попадут в раздел «Collaborate with maintainers»:

Из данного анализа вы можете понять, как много проблем в том или ином проекте, требующих решений для совместимости с Drupal 10. Для каждого проекта есть специальная ссылка «Issues», которая ведёт на страницу всех задач проекта с поисковым запросом «Drupal 10». Вы можете посмотреть, есть ли готовый патч, или помочь в решении данных проблем.

¶Обновление до Drupal 10

После выполнения всех предыдущих этапов, остаётся только обновиться до Drupal 10!

Быстрая проверка перед тем, чтобы продолжить:

• Вы сделали резервную копию проекта.
• Ваш боевой сервер удовлетворяет системным требованиям Drupal 10.
• Вы используете актуальную версию Drupal 9.
• Ваши модули и темы оформления не содержат устаревшего кода и шаблонов.
• Все сторонние модули, используемые на проекте, имеют поддержку Drupal 10.
• Upgrade Status — если вы его использовали, он должен быть отключен или вовсе удалён с проекта до обновления.

Для того чтобы обновиться до Drupal 10, вам достаточно запросить новые версии Drupal пакетов.

Запрашиваем новые версии пакетов для Drupal ядра:

$ composer require 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10' --update-with-dependencies --no-update

Если вы используете require-dev, вам также необходимо запросить новые версии пакетов предоставляемых ядром:

$ composer require 'drupal/core-dev:^10' --dev --update-with-dependencies --no-update

После того как обновили версии, необходимо запустить само обновление:

$ composer update

После того как обновление завершилось, не забудьте запустить обновление баз данных: либо перейдя на /update.php, либо при помощи Drush:

$ drush updb

На этом всё! Ваш проект должен работать на Drupal 10.

¶Ссылки

• Upgrading from Drupal 8 to Drupal 9 (or later) (англ.), drupal.org