Een Laravel-applicatie upgraden van PHP 8.1 naar 8.3 of 8.4: een praktische checklist

PHP 8.1 is op 31 december 2025 end of life gegaan en kreeg geen PHP2Shell-release. Een Laravel-applicatie die er nog op draait, moet naar 8.3 of 8.4. De PHP-wissel zelf duurt minuten. De tijd gaat zitten in drie andere plekken: de frameworkversie, de afhankelijkheden en de serverconfiguratie die na de overstap nog naar 8.1 wijst. Deze checklist dekt alle drie.

1. Controleer eerst de frameworkversie

Elke Laravel-release ondersteunt een reeks PHP-versies, en die reeksen zijn smaller dan mensen verwachten:

• Laravel 9 ondersteunt PHP 8.0 tot en met 8.2 en verloor de beveiligingsondersteuning in februari 2024.
• Laravel 10 ondersteunt PHP 8.1 tot en met 8.3 en verloor de beveiligingsondersteuning in februari 2025.
• Laravel 11 vereist PHP 8.2 of nieuwer en verloor de beveiligingsondersteuning in maart 2026.
• Laravel 12 en 13 zijn de huidige doelen; 12 vereist PHP 8.2 of nieuwer, 13 vereist PHP 8.3 of nieuwer.

Controleer de exacte data in de releasenotities van Laravel voordat je plant, want ze verschuiven. Het praktische gevolg: een applicatie op Laravel 9 kun je niet zomaar naar PHP 8.3 omzetten; die heeft eerst een framework-upgrade nodig, en dat is het grotere project. Laravel 10 kan op 8.3 draaien, wat het een bruikbare tussenstap maakt, maar het is zelf niet meer ondersteund, dus plan ook de volgende stap.

Vind je versie met php artisan --version of in composer.lock.

2. Laat Composer vertellen wat de overstap blokkeert

Voordat je de server aanraakt:

composer why-not php 8.3
composer why-not php 8.4

Elk vermeld package geeft aan die PHP-versie niet te ondersteunen. Sommige hebben een update nodig, andere zijn verlaten en moeten worden vervangen. Kijk ook in composer.json naar een config.platform.php-regel; zet die een oude versie vast, dan lost Composer afhankelijkheden op alsof de server nog 8.1 draait en installeer je packages die niet op 8.3 kunnen draaien.

Werk daarna bij op een branch, met de doelversie van PHP lokaal geïnstalleerd:

composer update --with-all-dependencies

Bekijk de diff van composer.lock. Grote versiesprongen van packages verdienen een blik op hun upgradenotities.

3. Draai de testsuite onder de nieuwe versie

Heeft de applicatie tests, draai ze dan eerst op de doelversie van PHP. Heeft ze die niet, dan is dit het moment om een handvol rooktests te schrijven voor de belangrijkste routes: inloggen, de belangrijkste formulieren, betalingen of exports, geplande commando's. Ze betalen zich terug tijdens deze upgrade en de volgende.

Statische analyse helpt ook. PHPStan of Larastan op een bescheiden niveau markeert de meeste typegerelateerde breuken die anders pas tijdens runtime verschijnen, en Rector heeft regelsets voor de wijzigingen van 8.2 tot en met 8.4.

4. De deprecations die ertoe doen

Van 8.1 naar 8.4 zijn dit de wijzigingen waar de meeste Laravel-codebases over struikelen:

• Dynamische eigenschappen (deprecated in 8.2). Eloquent-modellen hebben er geen last van omdat ze __get en __set implementeren, maar gewone klassen die niet-gedeclareerde eigenschappen zetten, vaak in oudere serviceklassen of value objects, geven nu deprecation-meldingen en breken in een toekomstige release. Declareer de eigenschappen of voeg tijdelijk het attribuut #[\AllowDynamicProperties] toe.
• ${var}-interpolatie in strings (deprecated in 8.2). Gebruik {$var}.
• utf8_encode() en utf8_decode() (deprecated in 8.2). Gebruik mb_convert_encoding().
• null doorgeven aan niet-nullable parameters van interne functies (deprecated sinds 8.1, nog steeds een veelvoorkomende bron van meldingen). Typisch: trim($request->input('name')) als de invoer ontbreekt.
• Impliciet nullable parameters (deprecated in 8.4): function f(string $x = null) moet function f(?string $x = null) worden.

Zet error_reporting(E_ALL) en log deprecations op staging, zodat ze vóór productie boven water komen.

5. De serveronderdelen die nog 8.1 zeggen

Hier "slagen" upgrades terwijl de site nog op de oude versie draait. Doorzoek de server op 8.1:

• Webserver: Nginx fastcgi_pass unix:/run/php/php8.1-fpm.sock of een Apache-FPM-proxy die naar de oude socket wijst.
• Het php-commando op het pad: update-alternatives --config php op Debian en Ubuntu, anders blijven cronjobs en artisan-commando's 8.1 draaien.
• Cron: scheduler-regels die /usr/bin/php8.1 artisan schedule:run aanroepen.
• Queue-workers: Supervisor- of systemd-units die php8.1 artisan queue:work draaien, Horizon inbegrepen. Na de wissel php artisan queue:restart, zodat draaiende workers het nieuwe binaire bestand oppakken.
• Octane, FrankenPHP of RoadRunner: het serverproces moet met de nieuwe runtime worden herstart.
• OPcache: herstart PHP-FPM na de deploy zodat de opcodecache wordt geleegd.
• Docker: de tag van de basisimage (php:8.1-fpm naar php:8.3-fpm of 8.4), plus installatieregels van extensies die naar de versie verwijzen.

Zodra nergens meer naar de oude pakketten wordt verwezen, verwijder je ze, zodat een toekomstige vergissing niet kan terugvallen op een ongepatchte runtime.

6. Omschakelen, controleren, bewaken

Gebruik een onderhoudsvenster, maak een back-up, schakel de FPM-pool en de webserverconfiguratie om, herstart, en controleer met php -v, een phpinfo-pagina en het eigen health-endpoint van de applicatie. Houd daarna een paar dagen de logboeken in de gaten: deprecation-meldingen uit zelden gebruikte routes duiken vaak een week later op.

Wil je een tweede paar ogen op de inventarisatie of de upgrade zelf, stuur ons dan de Laravel-versie, de huidige PHP-versie en waar de applicatie wordt gehost.