Skip to main content

Inleiding

Laravel 9 is uitgebracht op 8 februari 2022. Deze gids zet de stappen voor de upgrade van Laravel 8.x naar 9.x op een rij, samen met de wijzigingen met de grootste impact.
De geschatte tijd voor de upgrade is ongeveer 30 minuten. Afhankelijk van je gebruik van e-mailverzending, filestorage, custom casts en overrides van corekwlassen van het framework kan het werk echter toenemen.

Automatisch upgraden met Laravel Shift

Je kunt de upgrade ook automatiseren met Laravel Shift. Shift helpt bij het bijwerken van composer.json en de configuratiebestanden, en is daarmee een handig startpunt voor het controleren van de verschillen.

Wijzigingen per impactniveau

Impact: hoog

  • Dependencies bijwerken
  • Migratie naar Flysystem 3.x
  • Migratie naar Symfony Mailer

Impact: middel

  • De methodes firstOrNew / firstOrCreate / updateOrCreate van BelongsToMany
  • Custom casts en het gedrag met null
  • Standaardtimeout van de HTTP-client
  • Toevoeging van PHP-returntypes
  • Hernoemde schema-instelling voor Postgres
  • Vervallen van de methode assertDeleted
  • Verplaatsing van de lang-directory
  • Wijziging van de wachtwoordregel
  • Wijziging van de methodes when / unless
  • Behandeling van niet-gevalideerde arraykeys bij validatie

Upgradestappen

Dependencies bijwerken

Impact: hoog Laravel 9 vereist PHP 8.0.2 of hoger. Loop eerst de dependencies in composer.json na.
Daarnaast zijn voor de betreffende applicaties de volgende updates nodig.
  • Verwijder facade/ignition en vervang het door spatie/laravel-ignition:^1.0
  • Gebruik je pusher/pusher-php-server, werk die dan bij naar ^5.0
  • Controleer of de third-party packages die je gebruikt een Laravel 9-compatibele versie hebben
  • Gebruik je het Vonage-notificatiekanaal, bekijk dan ook de aparte upgradegids
Installeer daarna de dependencies.

PHP-versievereiste

Impact: hoog Laravel 9 vereist PHP 8.0.2 of hoger. Zorg dat de PHP-versie in je CI, lokale ontwikkelomgeving en productieomgeving overeenkomt voordat je de upgrade doorvoert.

Migratie naar Symfony Mailer

Impact: hoog Een van de grote wijzigingen in Laravel 9 is de migratie van SwiftMailer, waarvan het onderhoud in december 2021 eindigde, naar Symfony Mailer. Applicaties die alleen het gebruikelijke Mail::to()->send() gebruiken worden weinig geraakt, maar raak je de low-level API van SwiftMailer direct aan, dan moet je dit nalopen.

Driver-dependencies

Van withSwiftMessage naar withSymfonyMessage

De methodes send, html, raw en plain van Illuminate\Mail\Mailer geven nu geen void maar een Illuminate\Mail\SentMessage terug. Ook bevat de property message van het MessageSent-event nu een Symfony\Component\Mime\Email in plaats van een Swift_Message.

De SMTP-configuratie nalopen

In Symfony Mailer is de SMTP-optie stream vervallen; de ondersteunde instellingen verhuizen naar het topniveau.
Het expliciet instellen van auth_mode is ook niet meer nodig. Het is veiliger om e-mailadressen vóór het verzenden te valideren, in plaats van ongeldige adressen na verzending op te ruimen.

Migratie naar Flysystem 3.x

Impact: hoog Laravel 9 heeft de interne implementatie van de Storage-facade bijgewerkt van Flysystem 1.x naar 3.x. De bestandsbewerkingsmethodes zijn zoveel mogelijk compatibel gebleven, maar er zijn verschillen rond excepties, returnwaarden en adapterregistratie.

Extra drivers installeren

De belangrijkste gedragswijzigingen van Storage

  • put / write / writeStream overschrijven bestaande bestanden nu standaard
  • Bij een mislukte schrijfactie wordt false teruggegeven in plaats van een exceptie
  • Het lezen van een niet-bestaand bestand geeft null terug in plaats van een exceptie
  • delete op een niet-bestaand bestand geeft true terug
  • De cached adapter is verwijderd, dus je kunt de cache-key uit je disk-configuratie verwijderen
Wil je zoals voorheen een exceptie bij een mislukte schrijfactie, stel dan de optie throw in.
Registreer je een eigen filesystem-driver, pas de implementatie dan zo aan dat de callback van Storage::extend() direct een Illuminate\Filesystem\FilesystemAdapter teruggeeft.

firstOrNew / firstOrCreate / updateOrCreate van BelongsToMany

Impact: middel In Laravel 8 werd de attributenarray die je als eerste argument aan deze methodes doorgaf vergeleken met de tussentabel. In Laravel 9 wordt vergeleken met de tabel van het gerelateerde model.
Daarnaast accepteert firstOrCreate nu een tweede argument $values, waardoor het gedrag gelijkgetrokken is met de andere relaties.

Custom casts en null

Impact: middel In Laravel 9 wordt de set-methode van een custom cast ook aangeroepen wanneer je null toewijst aan het gecaste attribuut. Casts die geen rekening houden met null kunnen na de upgrade excepties gooien.

Standaardtimeout van de HTTP-client

Impact: middel De standaardtimeout van de HTTP-client is nu 30 seconden. Voorheen kon hij onbeperkt blijven wachten.

Toevoeging van PHP-returntypes

Impact: middel In Laravel 9 zijn, in lijn met de vereisten van PHP zelf en Symfony, returntypes toegevoegd aan diverse coreklassen. Extend je coreklassen van Laravel en override je methodes zoals offsetGet, offsetSet, jsonSerialize, open of read, voeg dan dezelfde returntypes toe aan je eigen implementaties.

Hernoemde schema-instelling voor Postgres

Impact: middel Stel je in een Postgres-verbinding een zoekpad in, wijzig dan de keynaam in config/database.php van schema naar search_path.

Van assertDeleted naar assertModelMissing

Impact: middel Vervang assertDeleted, dat je gebruikte om te controleren of een model is verwijderd, door assertModelMissing.

Verplaatsing van de lang-directory

Impact: middel In nieuwe Laravel 9-applicaties staan de taalbestanden niet meer in resources/lang, maar in de directory lang in de projectroot. Laat je je bestaande app gewoon draaien, dan is de impact klein, maar als je richting de nieuwe skeleton wilt of vanuit een package vertaalbestanden publiceert, loop dit dan na.

Wijziging van de wachtwoordregel

Impact: middel De regel password, die controleert of een waarde overeenkomt met het wachtwoord van de ingelogde gebruiker, is hernoemd naar current_password.

Wijziging van de methodes when / unless

Impact: middel In Laravel 8 werd een closure die je aan when of unless doorgaf zelf als truthy geëvalueerd, waardoor de conditionele tak onbedoeld kon worden uitgevoerd. In Laravel 9 wordt de closure uitgevoerd en wordt de returnwaarde als voorwaarde gebruikt.

Behandeling van niet-gevalideerde arraykeys

Impact: middel In Laravel 9 worden niet-gevalideerde arraykeys altijd uitgesloten van de array die validated() teruggeeft. Wil je het compatibele gedrag van Laravel 8 behouden, roep dan expliciet includeUnvalidatedArrayKeys() aan.

Samenvatting

Bij de upgrade van Laravel 8 naar 9 draait het vooral om de update naar PHP 8.0.2, de migratie naar Symfony Mailer en de overstap op Flysystem 3.x. Door e-mailverzending, storage, custom casts en testhelpers vooraf te controleren, verminder je problemen na de upgrade.

Referenties

Laatst gewijzigd op 6 september 2026