Обновление сайта с Drupal 9 на Drupal 10

Релиз Drupal 10 состоялся в декабре 2022 года, на фоне чего клиенты всё чаще приходят в Drupal-студии с запросом на обновление версии CMS до свежей. На официальном сайте Drupal можно изучить, на каком ядре и в каких количествах работают сайты по всей планете — видно, что пока растёт число сайтов на десятой версии, с её предшественниками всё наоборот.

Если у вас уже есть сайт на Drupal, то его обновление займёт от 20 до 200 часов — объём контента, контрибных и кастомных модулей, профайлов и тем, а также наличие на сайте сторонних сервисов влияют на продолжительность процедуры. Последовательность обновления давно прописана и понятна, что лишает эту работу творчества, а потому её хотелось бы сделать поскорее. На основе лучших практик и своих взглядов на процесс мы собрали инструкцию, как сократить время на обновление Drupal-сайта примерно в два раза.

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

Зачем обновлять версию ядра Drupal

Представьте, что вы вышли на улицу: этот город, район, дорога вдоль домов и сам дом знакомы вам много лет, а до вас здесь жили ваши родители. Все вы помните времена, когда место было чище и спокойнее, а теперь тут всё реже появляются даже уборщики мусора и полиция — район стал ульем криминала и маргиналов. Заблудившиеся здесь люди уйдут отсюда в лучшем случае без денег и смартфонов. Что делать? Можно лично воевать с бандами, создать общественную дружину для контроля за порядком, вставлять новые стёкла вместо разбитых. А можно переехать в другой район или город, где за порядком следят власти. И сделать это так быстро, как это возможно.

Сайты на устаревающих и неподдерживаемых версиях Drupal чем-то похожи на когда-то цветущие, а теперь неблагополучные районы. Что делают владельцы почти 15 тысяч сайтов на Drupal 6 для поддержания их работы? Неужели сами выпускают патчи безопасности для модулей, не поддерживаемых ни разработчиками ядра, ни сообществом? Это напоминало бы ту самую замену выбитого окна: его разобьют снова, это тщетно. Можно стараться поддерживать интерфейс на современном уровне, но от него нет никакого толка, если через разбитые окна небезопасных модулей лезут хакеры и гигабайтами выносят данные о вас и ваших пользователях.

В целом, работа сайта на устаревших версиях Drupal негативно затрагивает:

• кибербезопасность. Если никто не занимается рефакторингом кода, на котором написан модуль, и не пишет для этих модулей патчи, образуется уязвимость, через которую хакеры будут делать на вашем сайте свои грязные дела — это станет заметно и по жалобам пользователей, и по директориям проекта, где вдруг появятся лишние папки и файлы с вредоносным кодом. Ущербы от кибератак измеряются десятками миллионов долларов;
• функциональность. С появлением новой версии Drupal большая часть сил дизайнеров и разработчиков бросается на то, чтобы духу времени отвечали возможности новой версии, а не старых. Поэтому сайты на старых версиях Drupal просто не могут решать современные задачи и радовать внешним видом;      
• работу с хостингом. Для хостинг-провайдеров нерентабельно держать и обслуживать оборудование, работающее со старыми версиями языка PHP и старыми версиями баз данных, с которыми работали прежние версии Drupal; 
• работу со сторонними сервисами. API всех существующих сейчас сервисов наверняка заточены под работу с современным программным обеспечением.

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

Опытные разработчики помнят, что обновляя ядро на версиях Drupal 7 и ниже, они были вынуждены переписывать темы оформления и править кастомный код. Объём изменений зависел от сложности сайта и количества кастомного кода, но после обновления версии Drupal это был в значительной степени новый сайт. В ядре Drupal 7 устаревший код хоть и помечался, но политика системы к этому не обязывала — разработчики делали это на своё усмотрение.

Drupal 8 принёс с собой новый подход к обновлению ядра этой CMS, который сохраняется и сейчас. В основе этого подхода лежит семантическое версионирование — принцип присвоения любому программному обеспечению мажорных, минорных и патч-версий, а также версий с маркировками, намекающими на промежуточный характер обновления, которое может вести себя неправильно. 

В Drupal 8 появились компоненты фреймворка Symfony, а он, в свою очередь, позволяет разработчикам обновлять Drupal через пакетный менеджер Composer, работающий с принципом семантического версионирования. Это открыло дорогу к поддержке обратной совместимости между версиями Drupal: неработающий код помечается, но удаляется постепенно, и у разработчика есть возможность найти новый способ сохранить функциональность сайта, которую этот код обслуживал. 

Таким образом, после прихода Drupal 8 значительно уменьшилась вероятность непредсказуемого появления ошибок при обновлении ядра. Вся кодовая база проверялась на наличие неблагонадёжных кусков кода (так называемый цикл депрекации), которые помечаются как устаревшие для их последующего удаления разработчиками сайтов. Как итог, обновление до Drupal 10 занимает не больше времени, чем обновление на какую-нибудь минорную версию.

Важное замечание: все рекомендации в этой статье справедливы только в случае, если вы будете обновляться с Drupal 9 на Drupal 10. Если же сайт работает на Drupal 7, то одним махом перескочить на Drupal 10 не получится — это уже называется миграцией сайта и требует других инструкций.

Что нужно знать и помнить перед обновлением до Drupal 10

• Сайт должен работать минимум на Drupal 9.4. Почему это важно? Пропустив эту версию и залетев в десятку, например, с Drupal 9.3, ваш сайт рано или поздно перестанет работать из-за устаревших API (Entity API, Database API и др.).
• Ключевая процедура в обновлении до Drupal 10 — это обновление обратных зависимостей. Composer — ваш главный друг в этой задаче.
• Кастомные и контрибные модули и темы должны быть актуальной версии.
• Для поиска и устранения проблем в PHP-коде проекта вам понадобятся либо интегрированная среда разработки PHPStorm, либо модуль Upgrade Status. Последний надо отключить перед самим обновлением и удалить после. 
• Ваш сервер должен быть технически готов к новой версии CMS. Ниже — требования к версиям языка PHP, веб-серверам и базах данных, с которыми совместим Drupal 10.

• убедитесь в будущей совместимости системы и проекта через проверку Database support for JSON: откройте в панели вкладку Reports и перейдите на страницу Status report — она должна быть в статусе Available. Другой способ проверить совместимость — через модуль Upgrade status: в той же вкладке Reports откройте страницу Upgrade status и прочтите отчёт Drupal core and hosting environment. 

Пошаговая инструкция быстрого обновления сайта с Drupal 9 на Drupal 10

1. Обновите свой сайт до последней версии Drupal 9 (9.4 минимум)

• Обновите ядро:

composer update "drupal/core-*" --with-all-dependencies

• Обновите все контрибные модули в Composer:

composer update

• Запустите апдейт базы:

drush updatedb   
drush cache:rebuild

• Убедитесь, что сайт работает.
• Добавьте или обновите патчи, если требуется.

2. Обновитесь до Drupal 10

Отредактируйте файл composer.json и обновите версию для ядра drupal/core-* до ^10.   

"require" : {   
"composer/installers" : "^2.0"   
"drupal/core-composer-scaffold" : "^10"    
"drupal/core-project-message" : "^10"    
"drupal/core-recommend" : "^10"

Помимо указанных компонентов, в composer.json могут также входить компоненты drupal/core-dev и drupal/core. 

Как только вы запустите composer update, начнётся обновление.

3. Примените патч совместимости к модулям без версии для Drupal 10

Такие патчи можно найти в разделе Issues соответствующего модуля, а сама issue называется Automated Drupal 10 compatibility fixes. Далее можно либо отредактировать версию ядра в composer.json, заменив “^10” на “10.0.9 as 9.5.9”, либо воспользоваться плагином composer drupal lenient.

4. Добавьте устаревшие модули и темы

Если вы используете на вашем сайте модули и темы, которые были удалены из ядра Drupal, то добавьте их контрибные версии в свой файл composer.json.

Например, так выглядит команда добавления темы Bartik, которая была дефолтной со времён Drupal 7, но к Drupal 10 сменилась на Olivero:

composer require 'drupal/bartik:^1.0'

5. Обновите версии совместимости в кастомных модулях и темах

• Удалите из файла my_module.info.yml строку core, если она есть (например, core: 8.x). 
• В строке core_version_requirement добавьте 10 версию, например вместо core_version_requirement: ^8 || ^9 должно получиться core_version_requirement: ^8 || ^9 || ^10.
• Если ваш сайт использует устаревшую тему в качестве базовой (например, тему Classy), то её можно поменять на рекомендуемую Starterkit: base theme: classy заменить в my_theme.info.yml на base theme: starterkit_theme.То же самое касается темы Stable, которую можно поменять на stable9. В этом случае нужно поменять библиотеку базовой темы и в Twig-шаблонах, если она там используется.

Пример: строка {{ attach_library('classy/node') }} меняется на {{ attach_library('starterkit_theme/node') }} ).

• Не забудьте включить starterkit_theme, если решили использовать её в качестве базовой темы — она должна появиться в конфигурационном файле core.extension.yml. В конце обновления сайта заменённые устаревшие темы можно будет удалить из файла composer.json.
• найдите и удалите в PHP-коде все вызовы устаревшего API и поправьте код так, чтобы использовался только новый API. 

Пример: Устаревшая функция drupal_get_path('module', 'my_module_name') меняется на \Drupal::service('extension.list.module')->getPath('my_module_name')

Если в качестве IDE вы используете PhpStorm, то в настройках проекта можно запустить проверку кода с помощью PHP_CodeSniffer:

• Установите PHP_CodeSniffer через Composer:

composer global require "squizlabs/php_codesniffer=*"

• В разделе Quality Tools зайдите в настройки Code Sniffer и задайте пути до файлов phpcs и phpcbf.
• В разделе Editor -> inspections выберите авто-проверку.

Как искать ошибки в коде с помощью Upgrade status:

• Во вкладке Reports откройте страницу Upgrade status.
• Изучите содержание раздела Drupal core and hosting environment.

6. Twig обновился до 3 версии, поэтому вам может понадобиться обновить ваши Twig-файлы.

Как обновить Twig-файлы с использованием PhpStorm:

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

Как обновить Twig-файлы с использованием Upgrade Status:

• Во вкладке Reports откройте страницу Upgrade status.
• Укажите собственные модули и темы и нажмите Scan selected.
• После сканирования исправьте указанные ошибки.

7. Обновите зависимости в ваших файлах .libraries.yml.

Например, если в зависимостях у вас есть библиотека core/jquery.once, то замените её на библиотеку core/once, так как теперь once — это отдельная библиотека. Соответственно, JS-код, где используется once, нужно отредактировать:

8. Убедитесь, что ваш код не устарел и удовлетворяет требованиям PHP 8.1.

Для проверки можно использовать модуль Upgrade status. Для этого добавьте с помощью Composer пакет phpcompatibility/php-compatibility в секцию require-dev, а после установки пакета проверьте код своего модуля командой:

phpcs -p ./path/to/my/module --extensions=php,module,inc,install,test,profile,theme --standard=vendor/phpcompatibility/php-compatibility/PHPCompatibility --runtime-set testVersion 8.1

Если всё ок, вы увидите, например, это: 

9. Если вы обновляете Drupal до 10.1.x, убедитесь, что после обновления конфигураций в файле core.extension.yml появился модуль Password Compatibility (phpass) (Password hashing is changed). 
10. Запустите обновление базы.

drush updatedb

После обновления сайта в Status report может появиться ошибка Mismatched entity and/or field definitions.

Её можно исправить, вставив код ниже в свой модуль и запустив обновление:

/**   
* Implements hook_update_N().   
*/   
function HOOK_update_8701() {

 $entity_type_manager = \Drupal::entityTypeManager();   
 $entity_type_manager->clearCachedDefinitions();

 $entity_type_ids = [];   
 $change_summary = \Drupal::service('entity.definition_update_manager')->getChangeSummary();   
 foreach ($change_summary as $entity_type_id => $change_list) {   
   $entity_type = $entity_type_manager->getDefinition($entity_type_id);   
   \Drupal::entityDefinitionUpdateManager()->installEntityType($entity_type);   
   $entity_type_ids[] = $entity_type_id;   
 }   

 return t("Installed/Updated the entity type(s): @entity_type_ids", [   
   '@entity_type_ids' => implode(', ', $entity_type_ids),   
 ]);   
}

После обновления вы не должны найти эту ошибку в Status report.

Шаблон шпаргалки для быстрого обновления сайта до Drupal 10

Однажды наш Drupal-разработчик обновляла не особо большой клиентский сайт до Drupal 10. В перспективе маячил ещё один подобный сайт. А сколько их ещё впереди, таких же или сложнее? Поэтому, чтобы не вспоминать каждый раз заново, что разработчик делала с тем или иным модулем и темой, она составила себе несколько таблиц с типичным поведением, которое надо применять к модулям, темам и конфигам, которые встречаются на проектах: поменять на dev или patch-версию, применить хук, пометить модуль как контрибный и т. п.      
 

В левой части таблицы — установленные на сайте модуль или тема, в правой — изменения, которые надо внести в файл composer.json, чтобы эти модули и темы работали на Drupal 10. Как интерпретировать комментарии в правой части:

• 10.0.9 as 9.5.9 — после применения патчей совместимости к модулям без версий для Drupal 10 редактируется версия ядра: “^10” меняется на “10.0.9 as 9.5.9”.
• Automated Drupal 10 compatibility fixes patch — если модуль или тема не имеют даже dev-версии для Drupal 10, либо поищите патч в Issues проекта либо сразу гуглите название модуля или темы вместе с названием issue: Automated Drupal 10 compatibility fixes patch.
• 5.x-dev@dev — модуль, не поддерживающий работу с Drupal 10, заменен на dev-версию.
• contrib now — модуля больше нет в ядре Drupal, поэтому его нужно прописать в composer.json. 

Эта таблица нужна для пометок об изменениях в config-файлах. В частности, описано, как обновляются старые темы на сайте на новые. 

В этой таблице фиксируются состояния зависимостей до их обновления в ваших файлах .libraries.yml и то, как их нужно обновить.

Благодаря этим подсказкам обновление второго сайта заняло у разработчика в два раза меньше времени.

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

Желаем вам безболезненного и быстрого обновления до последней версии Drupal!