Migration Migraine Manual

Drupal8logo
Jan Baelemans

Migration Migraine Manual

Ook zo zitten te blokken op een Drupal migration?

De oorsprong

Ik ben een wat meer generalistisch type ICT-er. Ik weet van heel veel dingen heel weinig. Dit in tegenstelling tot de expert. Die weet van weinig dingen heel veel. We hebben elkaar nodig. Behalve die ene die van heel veel heel veel weet. Hoi iWoz.

Het upgraden of updaten van je (Drupal) site gaat niet altijd even gladjes. Hier kan Drupal nog een puntje zuigen aan Wordpress of Joomla. Maar de (gedeeltelijke) ondersteuning van Composer maakt veel goed. Soms is het het handigst om een site opnieuw op te zetten, de inhoud en configuratie te kopiëren en voila, je site draait weer als een tierelier. Beter dan uren van geneuzel, gevloek en "burning the midnight oil".

Het idee

Met dit in gedachten kwam ik op het geweldige idee om een migratie op te zetten die een fluitje van een cent zou zijn. Hallo, het is ICT dus.....

Inmiddels zijn we weer een paar jaar op weg met Drupal 8. Vergruisd door de Drupal 7 goeroe's, aanbeden door nieuwe gebruikers en oude rotten die open staan voor nieuwe dingen. En na een lange weg en veel bloed, zweet en tranen tekent zich een CMS af dat de goedkeuring van Dries en de rest van de CMS-wereld kan wegdragen.

Persoonlijk vind ik de migratie de beste uitvinding van deze nieuwe generatie. Maar zeker niet de makkelijkste. Ben je dan ook nog zo stom om op een bewegend doel te schieten? Wat gisteren nog werkte is geen garantie voor vandaag.

De migration handleiding

Dus een kleine handleiding voor al die andere Drupal-newbie's die de verhalen lezen en denken "dat doe ik wel even" (fout #1 in ICT).

1- richt een lokale (ontwikkel-) omgeving in. Veel informatie vind je hier. Je hebt de keuze uit MAMP (PRO), docker en nog veel meer. Mijn omgeving bestaat uit MAMP PRO, Visual Studio Code (ondersteunt PHP, YAML, SQL, Javascript, MarkDown, MarkUp, JSON leesbaar maken), TablePlus en phpMyAdmin (database management), Xcode en meer.

2 - Download je source-site naar een lokale omgeving, zowel code als database.

3 - Richt je (nieuwe) target-site in, liefst met een composer-based distributie (composer create-project ........) of gebruik een cloud-based oplossing. Sommige zijn gratis (voor een beperkte periode)

4 - Stel je migratie samen. Info, Yaml, PHP (plugins) en meer. De theorie achter de migratie lijkt complex. In wezen is het een hoop gegenereerde PHP a.d.h.v. de gedefinieerde YML-bestanden en het verwerken van associatieve array's. Tutorials en meer vind je 

5 - Testen. Nu komen de valkuilen om de hoek kijken. Want als Drupal-digibeet heb je geen idee wat of hoe. Daarom deze tips.

5a - Installeer de Devel-module, installeer "migration tools" en installeer "migration plus" in je target site. Activeer/installeer "basic auth" in je source-site. Activeer/installeer "JSON:API" in je source-site of beter beide sites (hoewel sinds 8.7.? in de kern/core). Devel geeft je veel gereedschappen om variabelen te zien en bij te houden. JSON:API geeft een behoorlijke simpele manier informatie uit je site te halen, denk ook aan decoupled en zo. Tools en Plus hebben veel aanvullende handigheden, plugins en meer.

5b - Om de "interne" structuur van entiteiten te weten te komen? In de nieuwe site creëer een entiteit, bewerk en roep de Devel module aan (Devel-tab?). Je kunt dan de interne structuur (array) zien en de namen voor de attributen in het proces-gedeelte van je migratie.

5c - Wil je weten welke entiteiten je kunt opvragen met JSON:API? Klik op de route-information van de Devel-module en filter/selecteer alle "jsonapi" routes. Dan kun je een api-call samenstellen, b.v. Soms is er een documentatie-module beschikbaar die het ook laat zien soms niet. http://localserver/mysite/docroot/jsonapi/{object}/{bundle/type} en zie je alle occurences of specifieke (JSON:API werkt op basis van uuid) voor een entiteit (meer documentatie over JSON:API hier) op moet vragen. Problemen met autorisatie? Gewoon de anonieme gebruiker toegang geven tot alles (of het specifiek uitzoeken). Het is lokaal dus geen veiligheidsprobleem voor je echte site! Of je logt in in een andere tab of venster in de source-site, dit helpt soms ook. Maar bedenk, hoewel je denkt dat je de informatie krijgt kan er een response zijn waarbij je niet (alles van) een entiteit kunt zien.

5d - Zorg dat je kunt zien waarom er een AJAX-fout optreedt, of anderszins gelinkte PHP-fout. MAMP PRO geeft een makkelijke mogelijkheid het PHP-log te zien. Maar er zijn andere opties. Waar ik regelmatig tegenaan liep?

5d1 - Call to a function blabla() on NULL: attribuut niet goed gevuld of zijn naamgeving in de YAML-file van de betreffende migratie.

5d2 - Alles lijkt goed te gaan maar de entiteit wordt niet aangemaakt. Geen foutmelding, nada. De meeste (of alle?) objecten en occurences hebben een type en/of bundle. In sommige gevallen moeten de bundle en het type hetzelfde zijn (crop-images), vaak ook niet (type: media, bundle: document), type en bundle worden bepaald door de systeem-namen. Kun je zien door het object te bewerken. Gewoon even mee spelen... Media heeft twee attributen, type en bundle. Voor de overige content-entiteiten volstaat (meestal) alleen het type-attribuut waarin de bundel-waarde van media-entiteit wordt vermeld. Dus een media image heeft type "media" en bundle "image". Een page heeft type "page" en niet type "node" en bundle "page". Heeft mij enkele dagen gekost hier achter te komen, wees gewaarschuwd.

6 - Maak een moment-opname backup van/na iedere stap die is goedgedaan. zo voorkom je dat je telkens opnieuw van de grond af aan op moet bouwen (tenzij je dit leuk vindt?)