Prezentacja z wydarzenia DrupalDay z dnia 27.01.2022

1. Migrate API w Drupalu
Jarosław Bartman
Piotr Kamieniecki

2. kariera.droptica.pl
Poznaj nas:
● O firmie
● Ścieżka kariery
● Szkolenia i rozwój
● Benefity
● Praca zdalna
● Biura
● Projekty i klienci
● Po pracy
● Hardware i software
● Typowy dzień pracy
https://kariera.droptica.pl Social Media: #drupaldaypl
Oferty pracy
● Frontend Developer HTML, CSS
○ 5 000 - 8 500 zł netto (B2B)
● Junior PHP Developer
○ 5 000 - 8 500 zł netto (B2B)
● PHP Fullstack Dev - Laravel lub Symfony (Mid/Senior/TechLead)
○ 9 500 - 16 500 zł netto (B2B)
● Drupal Developer (Mid/Senior/TechLead)
○ 10 500 - 17 500 zł netto (B2B)

3. Agenda
1. Jak działa migration API w Drupalu?
2. Settings.php
3. Docker
4. Pomocne moduły
5. Proste migracje - drupal - co daje core
6. Demo prostej migracji
7. Proste migracje z mapowaniem - struktura yamla
8. Process pluginy w corze
9. Process pluginy z contribowych modułów
10. Migracje - lookupy itd.
11. Customizacja migracji
12. source prepare row, process, destination
13. Debugowanie.
14. Tipy, case studies, o czym pamiętać, co nie działa

4. Jak działa migracja?

5. Jak skonfigurować settings.php w przypadku
migracji z drugiej bazy?

6. Docker compose

7. Lista modułów związanych z
migracjami
- migrate – zawarty w core Drupala zawiera całe API bez którego migracje nie mają racji bytu
- migrate_drupal – zawiera migracje ze starszych wersji Drupala
- migrate_drupal_ui - udostępnia interfejs użytkownika do migracji ze starszych wersji Drupala.
- migrate_tools – zestaw komend drushowych do zarządzania i uruchamiania migracji
- migrate_plus – grupy migracji, dodatkowe process pluginy, destination plugin table
- migrate_source_csv – umożliwia migrację z plików CSV
- migrate_scheduler - umożliwia uruchamianie migracji jako zaplanowano zadanie w cron
- commerce_migrate - migrcja z commerce1 i uberfcart
Kompletna lista modułów:
https://www.drupal.org/docs/upgrading-drupal/drupal-8-or-later-migrate-modules

8. Drush
migrate:status/ms – wyświetla listę migracji I ich status
migrate:import/mim – uruchamia migracje:
dostępne opcje:
--all uruchamia wszystkie zarejestrowane migracje
--group=nazwa_grupy uruchamia migracje z danej grupy
--limit=LIMIT – migruje wyznaczoną liczbę elementów, przydatne w trakcie developmentu
–tag=TAG - uruchamia wszystkie migracje z danym tagiem
migrate:reset-status/mrs – resetuje stan migracji
migrate:rollback/mr – uruchamia rollback

9. Migracje dostarczone przez rdzeń
drupala

10. Migracje dostarczone przez rdzeń
Drupala
- Generowane automatycznie przez moduł migrate_drupal
- Są w stanie migrować typy zawartości, paragrafów, taksonomii, innymi słowy przenoszą
konfigurację
- Migrują prostą zawartość - pola tekstowe, pliki, obrazki.

11. Jak włączyć automatyczne migracje w
drupalu?
Po najmniejszej linii oporu:
1. Instalujemy moduły migrate, migrate_drupal, oraz migrate_drupal_ui
2. Wchodzimy na stronę konfiguracji migrate_drupal_ui: /upgrade
3. Wciskamy przycisk import
4. Podajemy wymagane dane odnośnie połączenia z bazą danych i lokalizację plików
5. Potwierdzamy operację
6. Profit?

12. Demo

13. Migracje dostarczone przez rdzeń Drupala

14. Własne migracje

15. Analiza pliku .yml migracji
- id - machine_name migracji. To co zobaczymy w oknie statusu
- Label - czytalny przez człowieka opis migracji
- Migration_tags - mając moduły migrate_tools i migrate_plus, możemy
odpalać migracje po tych tagach
- Source - definicja pluginu, z którego migracja skorzysta przy pobieraniu
danych
- Process - definiujemy tutaj mapowanie pól dostarczonych przez źródło na
pola docelowe w konwencji “pole_docelowe: pole_źródłowe”. W bardziej
zaawansowanych przypadkach będziemy tu także definiować
wykorzystywany process plugin
- Destination - definicja pluginu, odpowiedzialnego za zapisanie danych
docelowych w określony sposób. W 90% przypadków jest to
“entity:machine_name_encji”.
- Migration_dependencies - lista innych migracji, na których polega ta
migracja, potrzebne kiedy uruchamiamy wszystkie migracje, lub grupy, aby
Drupal był w stanie określić w jakiej kolejności je wykonać.
Wymagane minimum to: id, source, process i destination

16. Process plugins dostarczone przez core
Najważniejsze/najczęściej używane:
- default_value
- migration_lookup
- skip_on_empty
- file_copy
- sub_process
Pełna lista process pluginów
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/list-of-core-migrate-pr
ocess-plugins

17. Process plugins - migrate plus
Najważniejsze/najczęściej używane:
- entity_lookup
- skip_on_value
- merge
- transliteration
Pełna lista process pluginów
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/list-of-process-plugins
-provided-by-migrate-plus

18. Własne migracje
Kiedy piszemy własne migracje?
- Najczęściej kiedy to co dostarcza Drupal jest niewystarczające
- Kiedy dane w serwisie do którego migrujemy mają inne mapowanie:
- zmiana nazwy pola
- pole w serwisie docelowym składa się z kilku “starych” pól
- Nowy serwis korzysta z danych, które znajdują się poza strukturami Drupala:
- osobna tabela w bazie danych
- zewnętrzny plik CSV
- baza danych nie jest drupalowa (customowy CMS, Wordpress, cokolwiek innego)
Wymagane moduły: migrate.
Zalecane moduły: migrate_plus, migrate_tools, migrate_drupal
Opcjonalnie: migrate_tools_ui, migrate_drupal_ui

19. Czy napisanie własnej
migracji jest trudne?
To zależy

20. Własne migracje
- Tworzymy osobny moduł, który będzie odpowiedzialny za migracje
- Poszczególne grupy migracji trzymamy jako submoduły
- Pliki *.yml migracji umieszczamy w katalogu “migrations” w submodule
- Wszystkie tworzone pluginy umieszczamy w katalogu src/Plugins/migrate/* modułu
nadrzędnego, gdzie * oznacza typ pluginów, które tam przechowujemy, w celu
zwiększenia reużywalności.
- Identyfikatory migracji nie powinny zawierać innych znaków niż alfanumeryczne i _
- Dokumentacja w kodzie wszystkich pluginów jest dość dobra i często zawiera przykłady
użycia uwzględniające najczęstsze scenariusze, także należy z niej korzystać bez
żadnych obawień :)
Garść porad:

21. Demo

22. Ale co się właśnie stało?

23. Własne migracje
- Przenieśliśmy istniejące node’y wraz z paragrafami, nie tracąc żadnych informacji
- Użyliśmy tagu do uruchomienia grupy migracji
- Wykorzystaliśmy process plugin “migrate_lookup” by najpierw powiązać paragrafy z
obrazkami w migracji paragrafów, a następnie node z paragrafami, podczas migracji node’ów
- Stworzyliśmy pole tymczasowe, by przechować wynik działania process pluginu, a następnie
wykorzystaliśmy je do przeprowadzenia właściwego mapowania.

24. Własne migracje
Migration lookup:
Process plugin wykorzystujący tabelę z mapą migracji, do wiązania wartości między polami.
Pełna konfiguracja:
- Migration - przyjmuje listę migracji, w których
będziemy poszukiwać wartości
- Source_ids/source - lista wartości z source, które
zostaną przekazane do wyszukiwania. Definiując
source_id możemy przypisać konkretne wartości
do konkretnej migracji.
- Stub - którą migrację należy wykorzystać w
przypadku braku rezultatów do utworzenia
placeholderowej encji
- No_stub - domyślnie false, kontroluje tworzenie
placeholderów w przypadku gdy wynik
wyszukiwania jest pusty

25. Własne migracje
Co było pierwsze?
Jajko?
K
u
r
a
?
Koło nie ma początku? ¯_(ツ)_/¯

26. Stubs
Rozważmy następujący przypadek:
- Migrujemy listę artykułów
- Każdy artykuł ma pole z referencją
- Artykuły mogą odnosić się do innych artykułów
- Artykuły mogą odnosić się do siebie nawzajem

27. Demo

28. Process plugins - hall of fame
- Get - kopiuje wartość z pola source na pole destination - domyślny plugin wykorzystywany przez migracje
==
- Migration_lookup - przeszukuje mapę migracji w celu znalezienia id
- Extract - umożliwia wyciąganie danych z odpowiednich kluczy tablic asocjacyjnych
- Entity_lookup - młodszy brat migration_lookup - przeszukuje encje istniejące w Drupalu w poszukiwaniu
encji o zadanym typie i wartości
- Static_map - mapa mapująca wartośc wejściową na jedną z zdefiniowanych wartości
- Skip_on_empty - umożliwia zatrzymanie migracji, lub importu rekordu, jeśli wartość wejściowa pola jest
pusta, jeśli nie, przekazuje wartośc do następnego plugina w pipelinie.
- Concat - łączy wartości dwóch pól używając zadeklarowanego kleju

29. Kiedy wszystko inne zawiedzie -
własny process plugin

30. Własny process plugin
- Umieszczamy w katalogu srcPluginmigrateprocess
- Uzupełniamy adnotację
- Wartości przekazane w kluczu source yamla, dostępne są jako zmienna $value w metodzie transform
- Dodatkowe wartości można przekazać jako klucze, które dostępne będą w $this->configuration[klucz]
- Jeśli potrzebujemy Dependency Injection implementujemy ContainerFactoryPluginInterface
- Jedyna metoda jaką musimy zaimplementować to transform

31. Demo

32. Skąd idziemy? - Source pluginy

33. Source plugin
- Umieszczamy w katalogu srcPluginmigratesource
- Opisane są adnotacją DrupalmigrateAnnotationMigrateSource
- W najbardziej ogólnym przypadku implementują MigrateSourceInterface, oraz powinny implementować
RollbackAwareInterface
- W większości przypadków są rozszerzeniem klasy DrupalmigratePluginmigratesourceSourcePluginBase
- Sam moduł migrate z rdzenia dostarcza dwa source pluginy: EmbeddedData oraz EmptySource
- Pozostałe source pluginy dostępne z rdzenia pochodzą z modułów np. Node, Block
- Większość modułów contrib, istniejących zarówno w Drupalu 7 jak i nowszych wersjach dostarcza własne
source pluginy np. Paragraphs, wraz z przykładami użycia
- Najczęściej używanymi contrib modułami dodającymi source pluginy są:
- Migrate source CSV - dodaje migracje z plików CSV
- Migrate plus - dodaje migracje z JSONów i XMLi

34. Source plugin - przykładowa migracja z CSV
- Ids: tablica nazw kolumn identyfikujących rekord.
- Path: ścieżka do pliku csv, obsługiwane są także
filestreamy
- Header_offset: który rekord od góry zawiera
nazwy pól
- Fields: tablica zawierająca mapowanie pól,
kolejność rekordów musi odpowiadać kolejnym
kolumnom, name będzie nazwą wykorzystaną
później w mapowaniu
- Delimiter, enclosure, escape - co to jest - każdy
wie
Jeśli mamy plik CSV gdzie pierwszy rząd jest nagłówkiem, potrzebujemy jedynie ids i ścieżki do pliku

35. Demo

36. Własny source plugin - SQL
Stan zastany D7:
- Zliczanie odwiedzin node’ów w
tabeli
- Każdy wiersz tabeli odpowiada
jednym odwiedzinom
Docelowy D8:
- Zliczenia są teraz osobną encją
- Moduł nie dostarczył ścieżki migracji
Rozwiązanie?

37. Demo

38. Dokąd zmierzamy? - Kilka słów o
destination pluginach

39. Destination plugin
- Umieszczamy w katalogu srcPluginmigratedestination
- Opisane są adnotacją DrupalmigrateAnnotationMigrateDestination
- W większości przypadków są rozszerzeniem klasy DrupalmigratePluginmigratedestinationEntity
- Rdzeń dostarcza kilkanaście modułów destination, jednakże są to wariacje nt. EntityContentBase lub
EntityConfigBase
- Użycie pluginu powinno kończyć się przetworzeniem stworzonego row na encję.

40. Coś nie działa i co wtedy?

41. Debugowanie migracji
- Migrate_process_var_dump
- Migrate_devel
- dd() :D

42. Debugowanie migracji
Xdebug Pluginy migracyjne dd(),var_dump i inne metody VDDD
(Var Dump Driven Development)
+ Step debugging
+ Podgląd wszystkich zmiennych
+ Rozpoczęcie debugowania jest proste
jak wstawienie breakpointu w kodzie
+ Instalacja composerem, lub w dowolny
inny sposób
+ Są modułami Drupala, więc można je
extendować i dopasowywać
zachowania do przypadków
+ Printowany output jest czytelny i
sformatowany
+ Jeśli wiemy czego i gdzie szukać,
może być szybsze niż stosowanie
pozostałych metod
- Konfiguracja może nie być najprostsza
w zależności od środowiska
- Może mieć spory narzut na szybkość
przetwarzania
- Użycie wymaga dodatkowego pisania
- Służą raczej do sprawdzenia wartości
danych wejściowych i wyjściowych,
niekoniecznie pomaga zidentyfikować
to błąd
- Clutter w konsoli w przypadku
uruchamiania migracji drushem
- Trzeba wiedzieć gdzie dokładnie się
wpiąć w kodzie
- Wstrzymywanie wykonywania kodu
przez die(), powoduje dodatkowe kroki
zanim można powtórzyć test (reset
statusu migracji, rollback etc.)
- Clutter w konsoli

43. Debugowanie migracji
Pluginy migracyjne - przykładowy output:
Migrate_devel:
- Uruchamiamy migrate import z parametrem
–migrate-debug
- Wartości wejściowe
- Co i w jakich polach docelowych zostało
zapisane
- Pod jakimi ID docelowymi możemy szukać w
mapie tego źródła
-
migrate_process_vardump:
- Wpinamy w process pipeline
- Dostajemy dosłownie dump przetworzonej wartości

44. Znane pułapki

45. Znane pułapki
-
- Tworzenie innych encji “przy okazji” - przykładowo migrujemy node i podczas migracji tworzymy
powiązane z nim paragrafy - musimy pamiętać, że rollback “nie widzi” dodatkowych encji, więc po
rollbacku dodatkowe encje pozostaną. Rozwiązanie: własny source plugin z zaimplementowanym
osobnym rollbackiem, podpięcie się EventSubscriberem pod event ogłaszany na końcu rollbacku i
usunięcie dodatkowych encji etc.
- Używanie stubów - stuby są świetne, gdyż rozwiązują problem wzajemnych zależności, problem
pojawia się gdy używamy stubów między zależnymi między sobą migracjami, potrafi to zepsuć
zależności w grupach i tagach, co skutkuje uruchomieniem migracji w złej kolejności i błędami. W
najgorszym przypadku powoduje, że migracje trzeba odpalać ręcznie po kolei
- Zdarzają się moduły (np. group), które nie mają ścieżki migracji między swoimi kolejnymi wersjami,
planując migrację trzeba o tym pamiętać
- Migracje są dość “ciche”, częto wiadomości z modułów nie są nigdzie logowane, nie docierają do
wyjścia z konsoli, a wyjątki bywają mocno ogólne

46. Przydatne linki
https://www.drupal.org/docs/drupal-apis/migrate-api/migrate-api-overview
https://understanddrupal.com/31-days-of-migrations
https://drupalize.me/series/drupal-migrate

48. Pytania?

49. Czy moduł migrate tools jest w
corze?

50. Dziękujemy za
wasz cenny czas!
Imię i Nazwisko autora
Jarosław Bartman, jaroslaw.bartman@droptica.com
Piotr Kamieniecki, piotr.kamieniecki@droptica.pl
Dane Kontaktowe
WWW.DROPTICA.COM