Jak zaktualizować Drupala 8 lub 9 do Drupala 10? Kompleksowa instrukcja

Zmiany w świecie technologii cyfrowych są nieuchronne i konieczne. Dla użytkowników i deweloperów Drupala, jednym z kluczowych momentów jest migracja systemu do jego najnowszej wersji. W tym wpisie skupię się właśnie na procesie aktualizacji do Drupala 10, krok po kroku przedstawiając, jak się do tego przygotować, co sprawdzić i jakie działania podjąć, aby przejście było jak najbardziej płynne i bezproblemowe.

Dlaczego Drupal 10?

Nowa wersja Drupala została oficjalnie wydana 14 grudnia 2022 roku, stanowiąc ważny krok w ciągłym rozwoju tego systemu zarządzania treścią.

Przejście na Drupala 10 to kwestia dostępu do nowych funkcji i usprawnień, a także ważny aspekt bezpieczeństwa i stabilności Twojej strony internetowej. Wsparcie dla Drupala 9 zakończyło się 1 listopada 2023 roku, co czyni aktualizację nie tylko zalecaną, ale w niektórych przypadkach konieczną.

Różnice między Drupalem 9 a Drupalem 10

Drupal 10 przynosi szereg udoskonaleń mających na celu ułatwienie pracy i poprawę bezpieczeństwa. Nie wprowadza za to całkowitej zmiany struktury systemu, dzięki czemu przejście z poprzednich wersji nie wymusza na użytkowniku potrzeby adaptacji do zupełnie nowego środowiska.

Oto kilka kluczowych zmian w porównaniu z poprzednią odsłoną systemu:

• Olivero - nowy domyślny motyw frontendowy: Olivero zastępuje Bartik jako główny motyw frontendowy, wprowadzając świeży i nowoczesny design.
• Claro - nowy domyślny motyw administracyjny: skórka Claro zastępuje Seven, oferując bardziej przejrzysty interfejs administracyjny, który jest zaprojektowany z myślą o efektywności i wygodzie użytkowania.
• Częściowe zastąpienie jQuery przez JavaScript: ta zmiana odzwierciedla trend w rozwoju stron internetowych, gdzie JavaScript systematycznie wypiera jQuery dzięki swojej wydajności i elastyczności.
• Aktualizacja CKEditor do wersji 5: najnowsza wersja CKEditor została napisana całkowicie od nowa. Oferuje ona ogromne możliwości rozbudowy i integracji ze współczesnymi technologiami.
• Usunięte wsparcie dla PHP poniżej wersji 8.1: Drupal 10 wymaga PHP w wersji co najmniej 8.1.
• Symfony w wersji 6.2: W przeciwieństwie do swojego poprzednika, który wspierał ten framework już w wersji 4, najnowsza odsłona Drupala wymaga Symfony w wersji 6.2. Jest to duży krok w poprawie bezpieczeństwa oraz optymalizacji stron opartych na tym systemie zarządzania treścią.

Usunięte moduły i motywy

Kolejną ważną zmianą w najnowszej wersji Drupala jest usunięcie niektórych motywów i modułów, które miały już status “deprecated” w Drupalu 9. Są one nadal dostępne jako contributed modules, ale są rozwijane osobno i nie należą do core Drupala. Poniżej przedstawiamy ich listę:

Wymagane wersje PHP i bazy danych

Drupal 10 stawia pewne wymagania systemowe, które muszą zostać spełnione, aby zapewnić sprawną pracę platformy. Oprócz PHP w wersji 8.1 lub wyższej (zalecane minimum 8.1.6), należy także zadbać o odpowiednią wersję bazy danych. Listę kompatybilnych wersji przedstawiamy poniżej:

Microsoft SQL Server oraz MongoDB również są wspierane poprzez osobne moduły contribowe.

Przygotowanie do aktualizacji Drupala

Przed przystąpieniem do aktualizacji zalecam stworzenie kopii zapasowej witryny i bazy danych. W razie jakichkolwiek problemów pozwoli to na szybkie przywrócenie witryny do poprzedniego stanu. Upewnij się także, że Twój hosting obsługuje wymagane przez Drupala 10 wersje PHP oraz bazy danych, o czym napisałem wyżej.

Migracja z Drupala 8

W listopadzie 2021 roku zakończyło się wsparcie dla Drupala 8, co skutkuje brakiem dalszych aktualizacji bezpieczeństwa i wsparcia technicznego dla tej wersji. Warto więc pomyśleć o migracji na nowszy system.

Dla użytkowników Drupala 8 planujących przejść na Drupala 10, konieczna jest początkowa aktualizacja do wersji 9. Jest to ważny etap w procesie migracji, pozwalający na płynne dostosowanie się do najnowszych standardów i funkcji oferowanych przez “dziesiątkę”. Po zakończeniu tej pierwszej fazy aktualizacji, można przystąpić do kolejnych kroków. Więcej informacji i wskazówek dotyczących procesu podwyższenia systemu z Drupala 8 do 9 znajdziesz w naszym artykule, jak poprawnie zadbać o aktualizację Drupala.

Migracja z Drupala 9 do 10

W przypadku podniesienia wersji systemu z Drupala 9 do 10, warto przygotować się na to, że cały proces składa się z wielu kroków. Poniżej opisuję każdy z nich, aby ułatwić Ci przeprowadzenie samodzielnej migracji.

1. Aktualizacja PHP do wersji 8.1

Jeśli jeszcze nie posiadasz tej wersji lub wyższej, musisz przystąpić do aktualizacji. Przed jej rozpoczęciem sprawdź, czy wszystkie moduły i motywy na Twojej stronie są kompatybilne z nowszą wersją PHP. Przydatne narzędzia do tego procesu to PHP Codesniffer i PHP Compatibility.

2. Aktualizacja Drupala 9 do najnowszej wersji

Następnym krokiem jest aktualizacja Drupala 9 do wersji minimum 9.4.4 (zalecana jest jednak najnowsza wersja - 9.5.11). W tym celu możesz użyć poniższych komend:

composer update "drupal/core-*" --with-all-dependencies
drush cr -y
drush updb
drush cex -y

3. Odinstalowanie motywów ze statusem “deprecated”

W najnowszej wersji Drupala motywy Classy, Bartik, Stable oraz Seven zostały usunięte. Przed aktualizacją odinstaluj je zatem z poziomu /admin/appearance. Jeżeli jednak posiadasz jakieś motywy bazujące na powyższych, możesz zainstalować ich contribowe wersje, używając poniższych komend:

composer require drupal/seven
composer require drupal/classy
composer require drupal/bartik
composer require drupal/stable

4. Migracja do CKEditor 5

Migracja edytora do CKEditor 5 to proces, który może być bardziej skomplikowany niż standardowa aktualizacja, głównie ze względu na to, że CKEditor 5 został napisany od nowa. Nowa architektura przynosi wiele zaawansowanych funkcji i ulepszeń. Jednak z powodu kompletnego przepisania kodu, nie wszystkie wtyczki dostępne w CKEditor 4 będą bezpośrednio kompatybilne z nową wersją.

Przed migracją ważne jest dokładne sprawdzenie zgodności i dostępności używanych pluginów oraz ewentualne przepisanie ich na najnowszą wersję edytora. Więcej na ten temat przeczytasz w dokumentacji CKEditora. 

Jeśli wszystkie pluginy są kompatybilne, możesz przejść do dalszych kroków:

• W pierwszej kolejności udaj się do  /admin/modules i zainstaluj moduł CKEditor 5.
• Następnie przejdź do /admin/config/content/formats i kliknij przycisk “Configure” przy każdym formacie, dla którego chcesz zmienić edytor.

• Zmień edytor w polu zaznaczonym poniżej czerwoną strzałką i kliknij “Save” na dole strony. Postępuj tak dla każdego formatu wymagającego zmiany.

• W ostatnim kroku przejdź do /admin/modules/uninstall i usuń moduł CKEditor.

5. Aktualizacja modułów przy pomocy Drupal Upgrade Status

Przed rozpoczęciem właściwej aktualizacji zaleca się również zainstalowanie modułu Drupal Upgrade Status. Głównym zadaniem tego narzędzia jest analiza kompatybilności aktualnie zainstalowanych modułów i motywów ze standardami nowej wersji systemu. Dzięki temu użytkownicy mogą szybko zidentyfikować elementy, które wymagają aktualizacji lub modyfikacji przed przeprowadzeniem procesu migracji.

Pierwszym krokiem jest instalacja i włączenie modułu:

composer require drupal/upgrade_status
drush en upgrade_status

Następnie przejdź do /admin/reports/upgrade-status, zaznacz moduły do sprawdzenia i kliknij przycisk “Scan selected”.

Po zakończonym procesie skanowania otrzymasz informację zwrotną z listą modułów niekompatybilnych z Drupalem 10.

W moim przypadku występuje problem z modułem Custom module. Jak widać na poniższym obrazku, moduł Drupal Upgrade Status sam podpowiada rozwiązanie problemu. Jest to błąd związany z wersją core’a w pliku info.yml. Poprawiłem błędy w kodzie i zeskanowałem całość jeszcze raz - to samo rekomenduję Tobie.

Rozwiązuj problemy z kompatybilnością tak długo, aż pasek w prawym górnym rogu wskaże 100%.

W przypadku własnych modułów niestandardowych możesz łatwo samodzielnie wprowadzić zmiany w kodzie. Moduły contribowe najczęściej wystarczy podnieść do najnowszych wersji, wspierających Drupala 10.

Sprawy komplikują się w momencie, gdy używany przez Ciebie moduł nie posiada jeszcze wsparcia dla “dziesiątki”. Istnieje kilka rozwiązań tego problemu. Jednym z nich jest plugin  do Composera pozwalający na instalowanie modułów, które nie są jeszcze kompatybilne z Drupalem 10. Poniżej podpowiadam, jak to zrobić.

Pierwszym krokiem jest instalacja pluginu:

composer require mglaman/composer-drupal-lenient

Następnie dodaj moduł, który chcesz zaktualizować, używając komendy:

composer config --merge --json extra.drupal-lenient.allowed-list '["nazwa modułu"]'

Ostatnim krokiem jest stworzenie patcha dodającego kompatybilność Twojego modułu z D10 i wrzucenie go do composer.json.

Jeśli pomyślnie udało Ci się przejść cały proces, możesz przystąpić do kolejnego etapu aktualizacji.

6. Aktualizacja Drupal Core do wersji 10

Przed aktualizacją rdzenia Drupala, warto przejrzeć composer.json i usunąć wszelkie przestarzałe patche niekompatybilne z nowszą wersją. Po zakończeniu tego procesu zrealizuj dalsze kroki.

Wpisz w terminalu komendę:

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

Jeśli używasz core-dev, zastosuj tę:

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

Następnie podnieś w composer.json Drusha do najnowszej wersji:

composer require 'drush/drush:^12' --no-update

Uruchom komendę:

composer update

Jeśli wersje w Composerze podniosą się bez żadnych błędów, uruchom:

drush cr -y
drush updb
drush cex -y

7. Testowanie strony internetowej

Po aktualizacji do Drupala 10 istotne jest przeprowadzenie dokładnych testów strony internetowej w środowisku lokalnym. Upewnij się, że wszystkie kluczowe funkcjonalności oraz elementy witryny działają prawidłowo. Należy sprawdzić istotne funkcje, takie jak formularze, nawigację, działanie modułów czy integrację z zewnętrznymi usługami. Warto także przejrzeć dokładnie stronę pod kątem wizualnym oraz spojrzeć na logi w celu wykrycia potencjalnych błędów.

8. Wdrożenie na serwer testowy i produkcyjny

Po dokładnym przetestowaniu strony w środowisku lokalnym, kolejnym krokiem jest jej wdrożenie na serwer testowy. Jest to zalecane działanie, gdyż pozwala na przeprowadzenie dalszych testów w warunkach zbliżonych do rzeczywistego środowiska użytkowania.

Po pomyślnym przetestowaniu na serwerze testowym, następuje etap wdrożenia na serwer produkcyjny. Jest to ostateczna faza aktualizacji, podczas której strona zostaje uruchomiona w środowisku docelowym i staje się dostępna dla wszystkich użytkowników. Warto zadbać o to, aby proces ten był starannie zaplanowany i wykonany. Dzięki temu uda się zminimalizować czas przestoju i potencjalne zakłócenia w dostępności witryny.

Pamiętaj, aby przed wdrożeniem na serwer produkcyjny, jeszcze raz dokładnie sprawdzić hosting pod kątem wymagań Drupala 10, a także upewnić się, że zostały wykonane kopie zapasowe witryny i bazy danych.

Lista potencjalnych problemów w trakcie aktualizacji Drupala

W trakcie aktualizacji systemu do Drupala 10 możesz napotkać kilka różnych problemów. Zerknij na moją listę, aby wiedzieć, czego się spodziewać i jak sobie poradzić.

1. Funkcje usunięte oraz oznaczone jako “deprecated”

W Drupalu 10 wiele funkcji działających w Drupalu 9 zostało usuniętych lub oznaczonych jako “deprecated”. Może to powodować potencjalne błędy w logach. Rozwiązaniem problemu jest poprawa kodu lub napisanie łatek do modułów, w których występują. Dobrym narzędziem wspomagającym ten proces jest opisywany wcześniej moduł Drupal Upgrade Status.

2. Wymagany accessCheck()

Od wersji Drupal 10, wszystkie zapytania dotyczące encji zawartości muszą zawierać wywołanie metody ::accessCheck() przed ich wykonaniem. Jest to wymóg systemowy mający na celu zwiększenie bezpieczeństwa i kontroli dostępu.

3. Funkcja jQuery once

Funkcja jQuery once została usunięta z rdzenia Drupala 10, ale wciąż jest obecna w wielu modułach dostarczanych przez społeczność, co może skutkować błędami:

Uncaught TypeError: $(...).once is not a function

Potencjalne rozwiązania:

• Zmiana biblioteki core/jquery.once na core/once w *.libraries.yml modułu lub motywu.
• Zmiana funkcji $.once() na once() w plikach js’owych.

4. Moduły niekompatybilne z Drupalem 10

Częstym problemem przy aktualizacji jest brak kompatybilności modułów niestandardowych i contribowych z Drupalem 10. Potencjalne rozwiązania tego typu problemów opisałem w akapicie dotyczącym modułu Drupal Upgrade Status.

5. Zależności w Composerze

Próba aktualizacji dość często blokowana jest przez zależności różnych modułów w Composerze. Pomocnym narzędziem w rozwiązywaniu tego typu konfliktów będą komendy, które opisuję szerzej w kolejnym akapicie.

Lista przydatnych komend

Aby uprościć Twoje działania w Composerze, przygotowałem listę praktycznych komend do użycia w zależności od sytuacji.  

1. Composer why-not (można też używać composer prohibits)

Komenda ta wyświetla listę zależności uniemożliwiających aktualizację. Przykład zastosowania:

composer why-not drupal/core ^10

2. Flaga --no-update

Umożliwia dodanie nowej zależności do composer.json bez natychmiastowego aktualizowania jej i instalowania nowych pakietów. Przykład zastosowania:

composer require 'drush/drush:^12' --no-update

3. Flaga --dry-run

Pozwala na symulację procesu aktualizacji bez rzeczywistego wprowadzania zmian. Composer pokaże, jakie działania zostaną podjęte w czasie aktualizacji, ale nie dokona żadnych zmian w rzeczywistych plikach lub zależnościach projektu. Przykład zastosowania:

composer update --dry-run

Aktualizacja Drupala 8 lub 9 do 10 - podsumowanie

Proces aktualizacji do Drupala 10, choć wymagający pewnego wysiłku i zaangażowania, jest inwestycją, która może przynieść znaczące korzyści dla Twojej strony internetowej. To nie tylko krok naprzód w korzystaniu z najnowszych funkcji i usprawnień, ale również istotny aspekt w podnoszeniu bezpieczeństwa i dostosowania strony do najnowszych standardów webowych.

Mam nadzieję, że ten poradnik ułatwi Ci przejście przez ten proces i zapewni wszystkie niezbędne narzędzia, aby wykonać go skutecznie i bez większych trudności. A jeśli w którymś momencie uznasz, że potrzebujesz profesjonalnej pomocy w aktualizacji strony do Drupala 10, nasi doświadczeni programiści wykonają pełen upgrade lub wesprą Cię na wybranym etapie migracji.