Migratieconfiguratie bij upgrade naar Drupal 8

Maak je initiële migraties aan

• Maak migraties aan met drush migrate-upgrade --configure-only, zoals beschreven in de sectie «Upgraden met Drush».
• Zorg ervoor dat je een config/sync-directory hebt, waar de volgende stap bestanden zal wegschrijven.
• Exporteer de migraties met drush config:export.
• Maak je eigen migratiemodule aan.
• Kopieer alleen de YML-bestanden die je wilt gebruiken uit de map config/sync naar de map config/install van je nieuwe custom module, en bewerk ze om de waarden uuid te verwijderen en id, group, label en andere waarden aan te passen indien nodig.
• Kopieer het bestand migrate_plus.migration_group.migrate_drupal_7.yml uit config/sync naar de map config/install van je nieuwe custom module en hernoem het naar migrate_plus.migration_group.your_module.yml. Je hebt dit groepsbestand nodig omdat het database-instellingen bevat.

Beheer van migraties

• Begin met het migreren van gebruikersrollen en gebruikers voordat je nodes migreert.
• Wanneer je bestanden toevoegt aan de map config/install, herlees de map met iets als drush config-import --partial --source=modules/custom/your_module/config/install (hiervoor moet de module Config ingeschakeld zijn).

Velden hernoemen bij upgrade naar Drupal 8

Stel dat je in je Drupal 7-site een contenttype A hebt met de velden foo, bar en baz. Stel ook dat je het veld baz wilt hernoemen naar zot in Drupal 8. Zulke wijzigingen zijn eenvoudig door te voeren wanneer je upgradet met Drush.

• Maak migraties aan met drush migrate-upgrade --configure-only, zoals hierboven beschreven.
• Voer de node type- en veldmigratie uit. Dit genereert contenttype A en de velden foo, bar en baz.
• Maak handmatig het veld zot aan in Drupal 8. Verwijder het veld baz dat door de migraties werd aangemaakt maar dat je niet wilt gebruiken.
• De bijgevoegde module Migrate Plus laat je migraties beheren als configuratieobjecten, waardoor je ze flexibel kunt laden, aanpassen en opslaan. De afzonderlijke migraties die met drush migrate-upgrade --configure-only zijn aangemaakt, kun je nu bekijken via admin/config/development/configuration/single/export door «Migration» te kiezen als configuratietype. Kies de migratie voor nodes (A).
• Kopieer en plak de migratie naar admin/config/development/configuration/single/import, maar pas de veldmapping aan zodat het doelveld field_zot is, terwijl de bron nog steeds field_baz blijft. De exacte inhoud van de migratiedefinitie hangt af van het veldtype. Voor de anatomie van migraties, zie de voorbeelden in de Migrate API-documentatie.
• Na het importeren van de aangepaste migratie kun je de migratie voor nodes van type A uitvoeren met Drush en controleren dat de data correct in het veld zot terechtkomen.
• Herhaal de mappingwijziging voor de migratie van node-revisies (A), als je ook revisies wilt migreren.

Een andere manier om hetzelfde resultaat te bereiken is door het veld zot handmatig aan te maken zoals hierboven beschreven, en de veldmapping van de node-migratie (A) aan te passen via een implementatie van hook_migration_plugins_alter().

Eigen process-plugins schrijven

Als je eigen logica voor transformatie nodig hebt (als dit, dan dat), kun je overwegen een eigen process-plugin te schrijven.

Het voorbeeld in de Migrate API-documentatie gebruikt de gebruikersmigratie. Voor het bepalen van de taalcode van een gebruiker is if-else-logica nodig, zoals beschreven, en daarom biedt de User-module een eigen process-plugin UserLangcode.

Bovenstaand voorbeeld beschrijft hoe de plugin moet worden opgeslagen in de map MODULE/src/Plugin/migrate/process en hoe deze moet worden geannoteerd zodat hij bruikbaar is. Gebruik UserLangcode en andere process-plugins als voorbeelden bij het schrijven van je eigen plugin!

hook_migrate_prepare_row()

Als je eigen transformatielogica wilt implementeren, kun je ook hook_migrate_prepare_row() in je custom module implementeren en daar je logica toevoegen.

Zoals beschreven in de API-documentatie heeft deze hook drie argumenten:

• Row $row
• MigrateSourceInterface $source
• MigrationInterface $migration

Zoals beschreven in de API-documentatie kun je $migration->id() gebruiken om je logica te beperken tot een specifieke migratie.

Om een bronproperty in een variabele te lezen, gebruik je Row::getSourceProperty(). Bijvoorbeeld, als de bronrij een property type heeft, kun je zeggen: $type = $row->getSourceProperty('type');

Om een volledig nieuwe property in te stellen die je in de migratiedefinitie als bron kunt gebruiken, gebruik je Row::setSourceProperty().

Om databasequery’s uit te voeren op de bronsite, gebruik je $source->getDatabase()->query(), zoals beschreven in de Database API-documentatie.

Om een rij over te slaan tijdens de migratie, kun je een nieuw MigrateSkipRowException-object gooien.

hook_migration_plugins_alter()

Een andere manier om migraties aan te passen is door de functie hook_migration_plugins_alter() in je custom module te implementeren.

Zoals beschreven in de API-documentatie heeft deze hook één argument, namelijk een associatieve array van alle ontdekte migraties. Je kunt migraties aanpassen of verwijderen die je niet wilt uitvoeren.

Migrate Plus biedt het PREPARE_ROW-event

Als je je eigen respons op de prepare_row-handler liever objectgeoriënteerd schrijft in plaats van hook_migrate_prepare_row() te implementeren, kun je dat doen wanneer je de module Migrate Plus hebt ingeschakeld. Migrate Plus biedt het PREPARE_ROW-event, waarop je eigen event subscriber zich kan abonneren. Zie de Drupal 8 API-documentatie voor events. Voor een voorbeeld van het implementeren van een event subscriber in een andere context, zie dit voorbeeld uit de documentatie van de Simple FB Connect-module.