Upgrade Laravelu 12 na 13 bez výpadku

Prečo upgradovať, keď aplikácia beží

Najčastejší argument proti upgradu znie: aplikácia funguje, tak prečo do nej siahať. Problém je, že Laravel má pevne daný životný cyklus podpory. Každá major verzia dostáva opravy chýb približne rok a bezpečnostné záplaty približne dva roky od vydania. Keď toto okno uplynie, zostanete s frameworkom, do ktorého už nikto nezapracuje opravu zraniteľnosti.

Druhý dôvod je praktickejší. Čím dlhšie odkladáte upgrade, tým väčší skok musíte spraviť naraz. Upgrade o jednu verziu znamená prejsť zoznam zmien na jednej stránke dokumentácie. Upgrade o štyri verzie znamená prepisovať kód, ktorý medzitým nikto roky nečítal — a vy neviete, ktorá zmena spôsobila regresiu.

Tretí dôvod sa týka balíkov tretích strán. Spatie, Livewire, Filament či Sanctum vydávajú nové verzie naviazané na aktuálny Laravel. Ak zostanete na starej verzii frameworku, zamrznete aj na starých verziách všetkých balíkov — vrátane tých, ktoré riešia bezpečnosť.

Krok 1: audit pred zásahom do composer.json

Upgrade nezačína príkazom composer update. Začína zistením, čo vás môže zastaviť. Prvá vec, ktorú spustím, je kontrola priamych závislostí a ich kompatibility:

# zoznam priamych závislostí a aktuálnych verzií
composer show --direct --latest

# ktoré balíky bránia upgradu frameworku
composer why-not laravel/framework 13.0

# audit známych zraniteľností
composer audit

Výstup composer why-not je najdôležitejší. Ukáže presne, ktorý balík má v composer.json obmedzenie brániace novej verzii frameworku. Každý taký balík si zaraďte do jednej z troch kategórií:

• Má novú verziu — upgradnete ho spolu s frameworkom, žiadny problém.
• Nemá novú verziu, ale je aktívny — pozrite si jeho issues a pull requesty, autor na tom pravdepodobne pracuje. Počkajte pár týždňov.
• Je opustený — posledný commit pred dvomi rokmi, žiadna reakcia na issues. Toto je skutočná práca: nájsť náhradu alebo funkcionalitu prepísať vlastnými silami.

Opustené balíky sú dôvod, prečo upgrade niekedy trvá týždne. Preto ich hľadajte ako prvé, nie až keď sa upgrade zasekne.

Skontrolujte verziu PHP na serveri

Nová major verzia Laravelu zvyčajne zdvihne minimálnu požadovanú verziu PHP. Overte, čo beží na produkčnom serveri — nie to, čo máte lokálne:

php -v
php -m   # načítané rozšírenia

Ak produkcia beží na staršom PHP, upgrade PHP je samostatný projekt, ktorý treba spraviť pred upgradom frameworku. Nerobte oboje naraz — keď niečo praskne, nebudete vedieť čo za to môže. Prechodu medzi verziami PHP sa venujem v článku o rozdieloch medzi PHP 8.3 a 8.4.

Krok 2: testy ako poistka

Bez automatických testov je upgrade hazard. Po upgrade musíte overiť, že aplikácia robí to isté čo predtým — a manuálne preklikanie väčšej aplikácie zaberie deň a aj tak niečo prehliadnete.

Ak testy nemáte, neznamená to, že musíte najprv napísať kompletné pokrytie. Stačí pokryť kritickú cestu: prihlásenie, hlavný biznis tok (objednávka, rezervácia, vytvorenie záznamu) a všetky miesta, kde tečú peniaze. Tri dni písania testov ušetria týždeň hasenia.

// tests/Feature/ObjednavkaTest.php
it('vytvorí objednávku a odošle potvrdenie', function () {
    Mail::fake();

    $pouzivatel = User::factory()->create();
    $produkt = Produkt::factory()->create(['cena' => 2990]);

    $odpoved = $this->actingAs($pouzivatel)
        ->post('/objednavka', ['produkt_id' => $produkt->id, 'mnozstvo' => 2]);

    $odpoved->assertRedirect('/objednavka/potvrdenie');
    expect($pouzivatel->objednavky()->count())->toBe(1);
    expect($pouzivatel->objednavky()->first()->suma)->toBe(5980);
    Mail::assertSent(PotvrdenieObjednavky::class);
});

Takýto test odhalí regresiu v sekunde. Podrobnejšie o písaní testov píšem v článku o testovaní v Pest PHP.

Krok 3: samotný upgrade vo vetve

Upgrade robte vždy v samostatnej vetve, nikdy priamo v hlavnej. Postup je priamočiary:

git checkout -b upgrade/laravel-13

# uprav obmedzenia v composer.json na novú major verziu
composer update --with-all-dependencies

php artisan config:clear
php artisan cache:clear
php artisan view:clear

./vendor/bin/pest

Príznak --with-all-dependencies je dôležitý: bez neho Composer nechá staré tranzitívne závislosti a skončíte s neriešiteľným konfliktom.

Po upgrade prejdite oficiálnu stránku Upgrade Guide riadok po riadku. Nie preto, že by vás niečo iné čakalo — ale preto, že zmeny označené ako „nízka pravdepodobnosť dopadu" sú presne tie, ktoré vás dostanú v produkcii o tri týždne. Každý bod si odškrtnite a overte v kóde.

Rector na mechanické zmeny

Časť zmien je čisto mechanická — premenované metódy, zmenené signatúry, nahradené fasády. Na tie použite Rector, ktorý ich prepíše automaticky:

composer require rector/rector --dev
./vendor/bin/rector init

<?php
// rector.php
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/app', __DIR__ . '/tests'])
    ->withPhpSets(php84: true)
    ->withPreparedSets(deadCode: true, codeQuality: true);

# najprv náhľad zmien, až potom zápis
./vendor/bin/rector process --dry-run
./vendor/bin/rector process

Rector spúšťajte po malých dávkach a každú dávku commitnite zvlášť. Keď niečo pokazí, viete presne čo vrátiť.

Súbory, ktoré Composer neaktualizuje

Composer upraví vendor/, ale nedotkne sa vašich konfiguračných a bootstrap súborov. Tieto si porovnajte ručne s čerstvou inštaláciou novej verzie:

• bootstrap/app.php — registrácia middleware, výnimiek a routovania
• config/*.php — nové kľúče a zmenené predvolené hodnoty
• public/index.php — mení sa zriedka, ale mení
• phpunit.xml — zmeny v schéme a premenných prostredia

# čerstvá inštalácia bokom na porovnanie
composer create-project laravel/laravel:^13.0 /tmp/laravel-fresh
diff -u bootstrap/app.php /tmp/laravel-fresh/bootstrap/app.php

Krok 4: staging pred produkciou

Zelené testy neznamenajú, že je hotovo. Testy nepokryjú výkon, správanie fronty pri záťaži ani integrácie s externými službami, ktoré sú v testoch podvrhnuté. Nasaďte upgrade na staging s kópiou produkčnej databázy a nechajte ho tam aspoň pár dní.

Na stagingu overte hlavne:

• Frontu a plánované úlohy — spustite worker a sledujte failed_jobs. Serializované joby z obdobia pred upgradom sa môžu chovať inak.
• Odosielanie e-mailov — šablóny, prílohy, kódovanie diakritiky.
• Platobné a API integrácie — v testovacom režime, celý tok vrátane webhookov.
• Výkon — porovnajte časy odpovedí kľúčových endpointov s produkciou. Rozdiel o desiatky percent je signál, nie štatistická odchýlka.
• Generovanie assetov — npm run build po upgrade konfigurácie Vite.

Krok 5: nasadenie bez výpadku

Samotné nasadenie je najkratšia časť — ak je pripravené. Poradie krokov je podstatné:

1. Záloha databázy a overenie, že sa dá obnoviť. Záloha, ktorú ste nikdy neskúšali obnoviť, nie je záloha.
2. Nasadenie kódu do nového adresára (atomický deploy cez symlink), nie prepisovanie bežiacej verzie.
3. composer install --no-dev --optimize-autoloader v novom adresári.
4. Migrácie databázy — len aditívne zmeny, nikdy mazanie stĺpcov v rovnakom nasadení.
5. Prepnutie symlinku na novú verziu a reload PHP-FPM.
6. Reštart queue workerov cez php artisan queue:restart.
7. Kontrola logov prvých 15 minút.

# typická sekvencia v deploy skripte
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
sudo systemctl reload php8.4-fpm

Celý tento reťazec sa oplatí automatizovať — postup popisujem v článku o nasadení Laravelu cez GitHub Actions.

Ako často upgradovať

Laravel vydáva major verziu raz ročne, spravidla začiatkom roka. Najlacnejšia stratégia je upgradovať raz ročne, pár mesiacov po vydaní — vtedy už majú balíky tretích strán hotovú podporu a najhoršie detské choroby sú opravené.

Ak udržiavate viac projektov, zaveďte si jeden mesiac v roku ako „upgrade mesiac" a prejdite ich za sebou. Druhý a tretí projekt idú vždy rýchlejšie, lebo problémy sa opakujú.

Menšie verzie (patch a minor) aktualizujte priebežne, ideálne mesačne cez composer update s bežiacimi testami. Aplikácia, ktorá je stále pár týždňov od aktuálneho stavu, sa upgraduje na ďalšiu major verziu takmer bez práce.

Zhrnutie: checklist upgradu

• composer why-not laravel/framework 13.0 odhalil všetky blokujúce balíky
• Opustené balíky majú nájdenú náhradu alebo plán prepísania
• Produkčný server beží na požadovanej verzii PHP
• Kritická cesta aplikácie je pokrytá testami a testy sú zelené pred upgradom
• Upgrade prebieha v samostatnej vetve, nie v hlavnej
• Oficiálny Upgrade Guide je prejdený bod po bode vrátane zmien s „nízkym dopadom"
• Konfiguračné súbory sú porovnané s čerstvou inštaláciou
• Upgrade bežal na stagingu s kópiou produkčných dát aspoň niekoľko dní
• Fronta, e-maily a externé integrácie sú overené manuálne
• Záloha databázy existuje a jej obnova je vyskúšaná
• Nasadenie je atomické, s možnosťou okamžitého návratu na predchádzajúcu verziu