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 vancomposer.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/updateOrCreatevanBelongsToMany - 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 incomposer.json na.
- Verwijder
facade/ignitionen vervang het doorspatie/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
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 gebruikelijkeMail::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
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-optiestream vervallen; de ondersteunde instellingen verhuizen naar het topniveau.
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 deStorage-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/writeStreamoverschrijven bestaande bestanden nu standaard- Bij een mislukte schrijfactie wordt
falseteruggegeven in plaats van een exceptie - Het lezen van een niet-bestaand bestand geeft
nullterug in plaats van een exceptie deleteop een niet-bestaand bestand geefttrueterug- De cached adapter is verwijderd, dus je kunt de
cache-key uit jedisk-configuratie verwijderen
throw in.
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.
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 zoalsoffsetGet, 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 regelpassword, 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 dievalidated() 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
- Officiële upgradegids (Engels)
- laravel/docs 9.x
upgrade.md - Diff van de laravel/laravel-repository (8.x → 9.x)
- Laravel Shift — communitydienst die upgrades automatiseert
- Symfony Mailer-documentatie
- Flysystem 3-documentatie