Aktualizacja Laravela krok po kroku — od starej wersji do Laravela 13 bez niespodzianek

Aplikacja w Laravelu napisana kilka lat temu zwykle działa — i właśnie dlatego nikt jej nie aktualizuje. Problem narasta po cichu: framework i PHP wypadają ze wsparcia bezpieczeństwa, hosting wyłącza stare wersje PHP, a nowe biblioteki nie chcą się zainstalować. W tym tekście opisujemy, jak przeprowadzić aktualizację tak, żeby była nudna — czyli przewidywalna.

Gdzie jesteśmy we wrześniu 2026

Laravel wydaje wersję główną raz w roku. Każda dostaje 18 miesięcy poprawek błędów i 2 lata poprawek bezpieczeństwa (polityka wsparcia):

Laravel 10 — bez wsparcia od lutego 2025.
Laravel 11 — bez wsparcia od marca 2026.
Laravel 12 — już tylko poprawki bezpieczeństwa, do lutego 2027.
Laravel 13 — aktualna wersja z marca 2026, wymaga PHP 8.3+, wsparcie bezpieczeństwa do marca 2028.

Po stronie PHP (php.net): 7.4, 8.0 i 8.1 są po końcu wsparcia, 8.2 dostaje poprawki bezpieczeństwa tylko do końca 2026 roku. Rozsądny cel to dziś Laravel 13 na PHP 8.4 lub 8.5.

Krok 1. Inwentaryzacja

Zanim cokolwiek zmienisz, spisz stan: wersję PHP na serwerze, wersję Laravela i wszystkich pakietów z composer.json, pakiety frontendowe i sposób budowania assetów. Przy każdym pakiecie sprawdź, czy ma wersję zgodną z docelowym Laravelem. Pakiety porzucone przez autorów trzeba będzie wymienić — lepiej wiedzieć o tym na starcie niż w połowie prac.

composer outdated --direct
composer why-not laravel/framework ^13.0

Druga komenda pokaże, które pakiety blokują docelową wersję frameworka.

Krok 2. Testy jako siatka bezpieczeństwa

Jeśli aplikacja nie ma testów, dopisz je przed aktualizacją — przynajmniej dla najważniejszych ścieżek: logowania, płatności, kluczowych formularzy i procesów. Nie chodzi o pokrycie procentowe, tylko o odpowiedź na pytanie „czy po aktualizacji to działa tak samo jak przed nią”. Proste testy HTTP w PHPUnit albo Pest wystarczą na start i zostaną w projekcie na kolejne aktualizacje.

Krok 3. PHP przed Laravelem albo razem z nim

Każda wersja Laravela ma minimalną wersję PHP, więc często trzeba podnosić oba równolegle. Najczęstsze pułapki przy przejściu z PHP 7.4 na 8.x:

PHP 8.0 — porównanie 0 == "foo" zwraca teraz false, match jest słowem kluczowym, wiele ostrzeżeń zamieniło się w wyjątki TypeError, a zasoby cURL czy GD stały się obiektami (checki is_resource() przestają działać).
PHP 8.1 — przekazanie null do nienullowalnych parametrów funkcji wbudowanych (np. strlen(null)) generuje deprecation; w starym kodzie takich miejsc bywa dużo.
PHP 8.2 — dynamiczne właściwości obiektów są przestarzałe, chyba że klasa ma atrybut #[\AllowDynamicProperties].

Deprecations nie psują aplikacji od razu, ale warto je wyłapać w logach na środowisku testowym, zanim w kolejnej wersji PHP staną się błędami.

Krok 4. Laravel wersja po wersji

Oficjalne przewodniki (laravel.com/docs/{wersja}/upgrade) opisują zawsze skok o jedną wersję, więc przy starszej aplikacji przechodzimy je po kolei: 8 → 9 → 10 → 11 → 12 → 13. Po każdym kroku: composer update, testy, poprawki. Na produkcję i tak trafia to jednym wdrożeniem.

Kilka zmian, które najczęściej zaskakują przy dłuższym skoku:

Laravel 11 wprowadził odchudzony szkielet aplikacji (routing, middleware i wyjątki w bootstrap/app.php, bez klas Kernel). Istniejącej aplikacji nie trzeba przerabiać na nową strukturę — dokumentacja wprost tego nie zaleca, a stary układ jest wspierany.
W migracjach ->change() od Laravela 11 musi powtórzyć wszystkie modyfikatory kolumny, inaczej zostaną usunięte.
Carbon 3: diffInDays() i pokrewne zwracają liczby zmiennoprzecinkowe i mogą być ujemne.
Sanctum, Passport, Cashier i Telescope w nowszych wersjach nie ładują własnych migracji — trzeba je opublikować.
Przy przejściu na Laravel 13 zwróć uwagę na nowe domyślne ustawienia cache i sesji w szkielecie — zmiana serializacji sesji na JSON w istniejącej aplikacji wyloguje wszystkich użytkowników.

Krok 5. Narzędzia, które oszczędzają godziny

Rector z zestawem rector-laravel — automatycznie przepisuje powtarzalne zmiany w kodzie. Zalecana konfiguracja RectorConfig::configure()->withComposerBased(laravel: true) dobiera reguły do zainstalowanej wersji Laravela.
Laravel Shift — płatna usługa, która przygotowuje pull request z aktualizacją o jedną wersję; darmowy „Vite Converter” przenosi projekt z Laravel Mix na Vite.
Laravel Boost — przy przejściu z 12 na 13 udostępnia komendę prowadzącą agenta AI przez aktualizację.

Narzędzia robią mechaniczną część pracy. Decyzje — co z porzuconym pakietem, jak przepisać nietypowe miejsce — dalej należą do programisty.

Krok 6. Frontend: z Laravel Mix na Vite

Starsze aplikacje budują assety przez Laravel Mix. Przejście na Vite według oficjalnego przewodnika to: instalacja vite i laravel-vite-plugin, zamiana webpack.mix.js na vite.config.js, zmiana require na import, zmiennych MIX_* na VITE_* i dyrektywy mix() na @vite() w Blade.

Krok 7. Wdrożenie z drogą powrotu

Nową wersję uruchamiamy najpierw na środowisku testowym z kopią danych produkcyjnych. Wdrożenie planujemy na porę najmniejszego ruchu, z kopią bazy i możliwością szybkiego powrotu do poprzedniego wydania. Po wdrożeniu przez kilka dni obserwujemy logi — deprecations i rzadko używane ścieżki wychodzą dopiero przy prawdziwym ruchu.

Jak nie wracać do tego za trzy lata

Najdroższa jest aktualizacja o kilka wersji naraz. Podniesienie o jedną wersję raz w roku to zwykle kilka godzin pracy — w ramach normalnego utrzymania aplikacji. Opisujemy, jak to robimy, na stronie aktualizacji Laravel i PHP.

Podsumowanie

Cel na dziś: Laravel 13 na PHP 8.4 lub 8.5; Laravel 10 i 11 oraz PHP ≤ 8.1 są bez wsparcia.
Kolejność: inwentaryzacja, testy, PHP, Laravel wersja po wersji, frontend, wdrożenie z drogą powrotu.
Narzędzia: Rector z rector-laravel, Laravel Shift, Laravel Boost.
Regularność: jedna wersja rocznie kosztuje ułamek skoku o kilka wersji.

Masz aplikację na starej wersji i nie wiesz, ile pracy wymaga aktualizacja? Napisz do nas — zaczniemy od inwentaryzacji i planu.