Core-update via Composer

Deze documentatie is onvolledig. Voeg meer informatie toe.

Problemen bij het updaten naar Drupal 8.8.0 of nieuwer?
Belangrijke wijzigingen zijn doorgevoerd in Drupal 8.8.0 als onderdeel van het Composer-initiatief, wat op de lange termijn de Composer-workflows voor Drupal-sites aanzienlijk zal verbeteren. Er zijn echter enkele specifieke aandachtspunten die van invloed kunnen zijn op de upgrade vanaf eerdere versies.

Eerste stappen

Om te begrijpen hoe Composer de afhankelijkheden van Drupal beheert, zie Composer gebruiken met Drupal. Om te bepalen of Composer de juiste methode is voor updates, vergelijk de beschikbare opties.

Voor het gemak bevatten deze instructies ook Drush-commando’s die nodig zijn om de update te voltooien: veel mensen vinden Drush sneller en eenvoudiger dan het webgebaseerde beheerpaneel.

Als dit een bestaande Drupal-site is die eerder niet via Composer werd beheerd, zorg er dan eerst voor dat deze klaar is voor Composer.

Drupal 8 Core bijwerken

Controleer eerst of er daadwerkelijk een core-update beschikbaar is:

composer update --dry-run "drupal/*"

Dit toont eventuele beschikbare minor- of patchupdates. Gebruik eventueel de oudere syntax composer update "drupal/*" om te controleren op alle kernupdates. (Zie Semver 2.0 voor uitleg over major, minor en patchversies.) Als er geen regel begint met drupal/core, weet Composer niets over beschikbare updates. Noteer of er een regel is die begint met drupal/core-recommended. Als er een update beschikbaar is, ga dan verder met de onderstaande commando’s.

Eenstapsupdate-instructie

Als je bekend bent met het updaten van Drupal en de nodige voorzorgsmaatregelen hebt genomen, is de update net zo eenvoudig als:

composer update drupal/core --with-dependencies
drush updatedb
drush cache:rebuild

Vervang drupal/core door drupal/core-recommended als je site dit pakket gebruikt. Je kunt dit controleren in composer.json of in de uitvoer van composer update --dry-run.

Als je jouw Drupal-site ooit hebt gestart met het project drupal-composer/drupal-project, kan het bovenstaande commando mislukken. Lees dan de aanvullende notities hieronder.

Updaten naar versie 8.8.0 of nieuwer

De nieuwste versie van drupal-composer/drupal-project is compatibel met Drupal 8.8.x. Als je jouw site echter enige tijd geleden (2019 of eerder) hebt gemaakt met deze template, moet je mogelijk enkele eenmalige aanpassingen doen bij de eerste update naar 8.8.0 of hoger. Deze aanpassingen worden verderop beschreven.

Als je Drupal 8 niet met Composer hebt geïnstalleerd

Als je Drupal 8 niet via Composer hebt geïnstalleerd, moet je jouw site omzetten naar een Composer-beheerd project om updates te kunnen uitvoeren via de bovenstaande commando’s. Zie Composer toevoegen aan bestaande sites voor een stapsgewijze handleiding om Composer handmatig toe te voegen aan bestaande Drupal 8-sites die eerder zonder Composer zijn geïnstalleerd.

Stapsgewijze update-instructies

Volledige stappen om Drupal 8 Core bij te werken met Composer:

1. Maak altijd een back-up van je bestanden en database voordat je begint met updaten.

• drush sql:dump maakt een databaseback-up aan.
• Aangezien drush archive-dump is verwijderd in Drush 9, moet je zelf standaard CLI-tools gebruiken om je mappen te back-uppen, meestal met uitzondering van de map vendor.

2. Lees de release notes. Sommige modules of thema’s moeten mogelijk worden bijgewerkt om te werken met een nieuwe minor versie (bijv. 8.3 → 8.4). Patchreleases (zoals 8.4.4 → 8.4.5) vereisen dit normaal niet.

3. Schakel de onderhoudsmodus in door de state system.maintenance_mode op 1 te zetten en vervolgens de cache te legen.

4. Als je hebt vastgesteld dat bepaalde modules of thema’s updates nodig hebben, volg dan de instructies voor het updaten van modules.

5. Update de Drupal-core en al zijn afhankelijkheden:

composer update drupal/core --with-dependencies

Vervang hierboven drupal/core door drupal/core-recommended als je die gebruikt.
Als je jouw site oorspronkelijk hebt gemaakt met drupal-composer/drupal-project, zie dan de opmerkingen hieronder over speciale stappen bij de eerste update naar 8.8.0 of hoger.

6. Voer de noodzakelijke database-updates uit met drush updatedb en wis de cache met drush cache:rebuild.

7. Als je configuratiebeheer gebruikt, exporteer dan de configuratie na de database-update met drush config:export --diff, zodat eventuele wijzigingen in configuratiebestanden worden vastgelegd.

8. Controleer of alles goed werkt:

• Bekijk het statusrapport op fouten.
• Als de Database Logging-module is ingeschakeld, voer enkele basisacties uit en controleer de logboeken op waarschuwingen of fouten.

9. Schakel de onderhoudsmodus uit met drush state:set system.maintenance_mode 0 en bouw de cache opnieuw op.

10. Controleer de site opnieuw als anonieme gebruiker.

In productieomgevingen

• Je hoeft de bovenstaande stappen niet te herhalen. composer install zal exact de versies uit composer.lock installeren, zodat alle omgevingen identiek zijn.
• Als je aparte dev-, staging- en productieomgevingen hebt, kopieer dan altijd de bestanden composer.json en composer.lock en voer in productie composer install --no-dev uit in plaats van een update. De vlag --no-dev voorkomt dat ontwikkelpakketten (debugmodules of testbibliotheken) worden geïnstalleerd.

Bijzondere aandachtspunten bij het updaten naar Drupal 8.8.0 en hoger

De officiële Drupal-beta-partner PreviousNext heeft een handige blogpost gepubliceerd over hun stappen om te upgraden van Drupal 8.7 naar de beta van 8.8.0 — nuttig voor site-eigenaren met soortgelijke problemen.

De belangrijkste oorzaak van problemen bij updates van eerdere Drupal-versies naar 8.8.0 via Composer is de overstap van communityproject drupal-composer/drupal-project naar het nieuwe officiële template drupal/recommended-project. De volgende stappen helpen om de installatie te corrigeren zodat standaard update-instructies zoals hierboven werken.

Verwijder de map /vendor

Het verwijderen van de map vendor kan soms conflicten oplossen tijdens Composer-updates:

cd your_install_dir
rm -rf vendor

Migreren van webflo/drupal-core-strict naar drupal/core-recommended

Voor 8.8.0 gebruikten veel sites het metapakket webflo/drupal-core-strict om afhankelijkheden te vergrendelen op de exacte versies die door Drupal Core werden gebruikt. Vanaf 8.8.0 biedt Drupal zelf het pakket drupal/core-recommended voor dit doel. De overgang gebeurt niet automatisch bij updates.

De eenvoudigste manier om te migreren en conflicten te vermijden, is composer.lock te verwijderen als onderdeel van de update. Let wel, dit kan ook andere afhankelijkheden bijwerken. Deze stappen zorgen voor een gecontroleerde migratie:

1. composer update
2. git add composer.lock; git commit
3. composer remove webflo/drupal-core-strict --no-update
4. composer remove drupal/core --no-update
5. composer require 'composer/installers:^1.7' --no-update
6. rm composer.lock
7. rm -rf vendor
8. composer require drupal/core-recommended:^8.8 --update-with-dependencies
9. git add composer.json composer.lock; git commit -m "Update naar Drupal 8.8.0 en gebruik drupal/core-recommended"

Migreren van webflo/drupal-core-require-dev naar drupal/core-dev

Als je site nog het metapakket webflo/drupal-core-require-dev gebruikt voor ontwikkelafhankelijkheden, verwijder dit dan en gebruik voortaan het officiële drupal/core-dev.

composer remove --dev webflo/drupal-core-require-dev
composer require --dev drupal/core-dev

Patches bijwerken

Als je patches toepast met cweagans/composer-patches, moeten deze mogelijk opnieuw gerolled worden. Werk daarna de patchverwijzingen bij in het gedeelte extra/patches van composer.json.

Conflicterende zachte afhankelijkheden bijwerken

Soms is een afhankelijkheid geïnstalleerd met een versie die niet compatibel is met de nieuwste Drupal-versie. In dat geval kun je bepaalde versies tijdelijk forceren met composer require, en ze daarna verwijderen.

composer require --update-with-dependencies \
drupal/core:^8.8.0 \
symfony/finder:^3.4 \
symfony/filesystem:^3.4

composer require --dev --update-with-dependencies \
drupal/core-dev:^8.8.0 \
symfony/debug:^3.4

composer remove -n symfony/finder symfony/filesystem
composer remove -n --dev symfony/debug

Database en configuratie bijwerken

drush updb
drush cr
drush config-export

Settings.php bijwerken

Vanaf Drupal 8.8.0 wordt het synchronisatiepad gedefinieerd in $settings in plaats van $config_directories. Pas dit dus aan van:

$config_directories['sync'] = 'foo/bar';

naar:

$settings['config_sync_directory'] = 'foo/bar';

Bekende problemen en oplossingen

Als composer update geen update uitvoert voor drupal/core, blokkeert mogelijk een andere afhankelijkheid. Controleer dit met:

composer prohibits drupal/core:8.5.0

en update de genoemde afhankelijkheden samen met drupal/core, bijvoorbeeld:

composer update drupal/core "symfony/*" --with-dependencies

Veel Composer-updateproblemen komen voort uit verouderde templates of foutieve instellingen in composer.json. Gebruik het aanbevolen Composer-template uit hoofdstuk 3.5 van de Drupal 8-handleiding “Composer gebruiken om bestanden te downloaden en bij te werken”. Zie ook Composer toevoegen aan bestaande sites voor stapsgewijze instructies.

Vanaf januari 2020 is drupal-composer/drupal-project niet langer het aanbevolen template voor Drupal 8.8 en hoger. Raadpleeg de communityhandleiding voor het starten van een site met Composer-templates.

Andere nuttige bronnen:

• Upgraden naar Drupal 8.4.0 en Drush 9 met Composer – blogpost door Benji Fisher (Isovera).
• Drupal Core 8.4 bijwerken: stapsgewijze gids – blogpost door PreviousNext.
• Upgraden naar Drupal 8.5 met Composer – blogpost door Eirik Morland (eiriksm).
• Composer kon niet updaten van 8.4.4 naar 8.5.0-alpha1 – discussie met oplossingen.
• Problemen met het updaten van je Drupal 8-site? Deze blog helpt je verder.

Als er fouten of waarschuwingen optreden tijdens het updateproces, lees deze zorgvuldig door en zoek in de issue queues naar mogelijke oplossingen voordat je verdergaat. Bij fatale fouten is het altijd aan te raden het proces te stoppen en opnieuw te beginnen met de eerder gemaakte back-up.