Zkušenosti s upgradem webů z Drupalu 8 na Drupal 9

Samozřejmě, Drupal 9 už nějaký ten pátek používám. Pro nové projekty. Ale zatímco dříve jsem experimentoval na svých projektech a až poté nasazoval novinky ke klientům, nyní to bylo obráceně. Pravdou je, že Drupal 9 zase tak velký experiment není. Jde prostě o evoluci Drupalu 8, který je léty již dostatečně prověřen.

K upgradům jsem se ve větším měřítku dostal až během prosince. Došlo i na Maxiorla, takže teď už koukáte na Drupal 9. Povýšení na novou verzi se osmičkáři nemusí bát. Rozhodně je ale dobré se připravit a vše otestovat bokem.

Vývojová kopie, aktualizace osmičky, Upgrade Status

Prvním krokem při uvažovaném upgrade na Drupal 9 je tedy vytvoření kopie webu. Já, nepoužívajíc Docker, jsem sáhl po klasickém lokálním Apache, v prostředí macOS rozběhnutém s využitím Homebrew. Na vývojový server se mi weby stěhovat nechtělo.

Následuje aktualizace na nejnovější verzi Drupalu 8.9.x a všech použitých modulů. To vám samo o sobě zajistí, že budete mít snad vše kompatibilní s Drupalem 9. Alespoň já tedy používám většinou takové moduly, které jsou aktivně udržované a nenarazil jsem na závažnější problém, kvůli kterému bych na podporu Drupalu 9 musel čekat.

Dalším krokem je instalace modulu Upgrade Status. Po zapnutí vám v administrační části Logy > Upgrade status zobrazí několik informací s výsledky kontroly kompatibility vašeho webu s Drupalem 9.

Kontrola prostředí, tedy webového serveru, verze PHP a verze databáze, samozřejmě proběhne oproti místu, kde máte testovací kopii webu. Není-li na stejném serveru, pak je to zavádějící a doporučuji se důkladně ujistit, že parametry serveru/hostingu odpovídají požadavkům Drupalu 9.

Povyšte na kompatibilní řadu modulů

U některých modulů se mi stalo, že byly aktualizované na nejnovější verze své stávající řady, ale ta ještě Drupal 9 nepodporovala. Z výstupu Upgrade status to snadno zjistíte. Pak stačí jen příkaz composer require drupal/modul :^číslo_verze s následnou aktualizací databáze a modul je povýšen.

Co s nekompatibilními moduly?

Naprostá většina modulů, která se s Drupalem 9 zatím nekamarádila, postrádala jen drobné změny v info.yml souborech nebo jednoduché úpravy kódu. A vždy jsem našel v diskusích na drupal.org patch, který to řešil.

Určitě nechcete řešit ruční patchování modulu. Doplňte si do projektu composer require cweagans/composer-patches. V souboru composer.json v kořenové složce svého projektu vyhledejte část extra{} a na její začátek přidejte příkazy pro patchování v následujícím tvaru:

        "patches": {
            "drupal/modul": {
                "váš popisek": "https://www.drupal.org/…/neco.patch"
            },
            "drupal/jiny_modul": {
                "váš jiný popisek": "https://www.drupal.org/…/jiny.patch"
            },
        },

Kdykoli spustíte příkaz composer install, patchování modulů se provede.

Upgrade na Drupal 9 a vaše vlastní moduly

Specifická situace se týká vašich vlastních modulů a témat vzhledu. Jejich kompatibilitu za vás nevyřeší žádný obecný patch na drupal.org. Pokud nepoužíváte žádné deprecated funkce, pak to bude bez práce. Ale na rovinu: já jsem třeba u Maxiorla na řadu modulů nesáhl od doby, co jsem je připravil, takže samozřejmě v nich byla řada deprecated volání.

Drupal 9 se totiž od Drupalu 8 liší především tím, že ruší věci, které byly v Drupalu 8.9 označeny jako zastaralé, ale zatím stále fungovaly. Příkladem takové funkce je třeba drupal_set_message(), kterou nově voláte jako \Drupal::messenger()->addMessage().

V první řadě se vraťte na stránku s hlášením Upgrade status. Zaklikněte svoje moduly a tlačítkem vespod spusťte jejich kontrolu. Pokud v nich kontrola najde problémy, zobrazí se v samostatné tabulce s možností si počet problémů rozkliknout a dozvědět se více.

Ty detailnější informace vás velmi dobře navedou. Uvidíte konkrétní soubor v modulu, kde je něco špatně a zároveň i návrh řešení. Takto vše projdete, poté spustíte kontrolu modulu znovu a jste hotovi. Ve výsledku vám bude fungovat jak v Drupalu 8.9, tak potom v ryzí devítce.

Upgradujeme jádro na Drupal 9

Jakmile máte všechna rozšíření kompatibilní, mělo by to jít jako po drátkách:

1. Ve složce /web/sites/default nastavte zápis pro soubory *settings.php a *services.yml.
2. Zavolejte příkaz composer require drupal/core-recommended:^9.0.0 drupal/core-composer-scaffold:^9.0.0 drupal/core-project-message:^9.0.0 --update-with-dependencies --no-update
3. Následně prostý composer update
4. Aktualizujte databázi, ideálně z příkazového řádku přes drush updatedb -y
5. Ujistěte se, že v composer.json máte "drupal/core": "^9.0.0",
6. Zrušte práva zápisu k souborům uvedeným v bodu 1.

Podrobně je tato část popsána zde v dokumentaci na drupal.org.

Jestliže patchujete info.yml soubory některých modulů tak, aby v nich byla uvedena kompatibilita s Drupalem 9, je potřeba je ošálit, aby si před aplikací patche mysleli, že běží na osmičce. Zařídí to následující příkaz, který upraví composer.json.

composer require "drupal/core:9.0.0 as 8.9.0"

Čísla verzí upravte na aktuálně dostupné a použité.

Co může kontrole kompatibility uniknout

Bohužel Upgrade Status není všemocný, takže nějaké drobnosti mu mohou uniknout. Při upgradu Maxiorla jsem na nějaké narazil.

Po upgrade uvidíte bílou stránku a v error logu hlášení: You have requested a non-existent service "path.alias_manager". Did you mean this: "path_alias.manager"?

Řešením je přepsat volání služeb z path.alias_manager na path_alias.manager. Tato změna se odehrála opět někdy v průběhu života Drupalu 8 a do verze 8.9 fungovalo kvůli zpětné kompatibilitě obojí. Ideálně, když vyhledáte všechny výskyty původního řetězce a necháte jej přepsat.

Kontrole v Upgrade Status v mém případě uniklo také volání getVocabularyId(), které je třeba nahradit za bundle().

Tyto problémy odhalíte velice snadno, bohužel ale až poté, co upgrade provedete. Proto je tak důležité mít testovací verzi a na ní vše připravit.

Nasazujeme na ostrý web

V momentě, kdy máte vše vyzkoušeno na testovací kopii, mělo by stačit provést překopírování vašich vlastních modulů (jestli ručně nebo Gitem, to je fuk, neřeším vaše workflow) a na produkci zavolat composer install s následnou aktualizací databáze.

Přeji vám, ať se vám upgrade na Drupal 9 podaří, máte na to čas do listopadu letošního roku. A budu rád, když se o své zkušenosti případně podělíte v komentářích nebo mi napíšete někam na sociální sítě.