Checklista migracji PHP — 30 punktów przed wdrożeniem [2026]

Checklista migracji PHP to lista kontrolna, która zamienia „przepiszemy kod na nowszą wersję" w przewidywalny proces z jasnymi krokami i punktami decyzyjnymi. Poniżej 30 punktów w pięciu fazach — od inwentaryzacji po monitoring po wdrożeniu — wraz z tym, jak zweryfikować każdy z nich. Możesz ją potraktować jako szablon planu migracji albo narzędzie kontroli, jeśli migrację prowadzi ktoś inny.

Najważniejsze: Kolejność faz ma znaczenie: najpierw zmierz (audyt), potem zabezpiecz (testy), potem przepisuj (Rector), potem wdrażaj (staging → produkcja), na końcu obserwuj (monitoring). Każda faza kończy się kryterium odbioru — bez jego spełnienia nie przechodzisz dalej.

Faza 1 — Inwentaryzacja i audyt zgodności

• Cel fazy: wiedzieć, co dokładnie przestanie działać na docelowej wersji PHP. Kryterium odbioru: lista blokad podzielona na „automatyczne", „ręczne" i „do wymiany biblioteki".

• 1. Spisz wersje środowiska — PHP (docelowe i obecne), wersja frameworka/platformy, wersja bazy danych. php -v, composer show, panel hostingu.

• 2. Uruchom PHPCompatibility — skan konstrukcji usuniętych i zmienionych: vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4-.

• 3. Uruchom PHPStan na poziomie 5 — wychwyci problemy typów i wywołań, które w nowej wersji staną się błędami.

• 4. Zrób przegląd zależności — composer outdated i composer why-not php 8.4: które pakiety wspierają docelową wersję, a które są porzucone.

• 5. Spisz rozszerzenia PHP — lista używanych rozszerzeń (php -m) i weryfikacja, czy wszystkie istnieją w docelowej wersji (np. mysql_* → mysqli/PDO).

• 6. Zidentyfikuj kod generowany — cache szablonów, pliki generowane przez ORM, kod vendor: wyklucz z migracji, żeby nie „naprawiać" plików, które zostaną nadpisane.

• Kryterium odbioru: dokument z listą blokad i wstępnym szacunkiem pracochłonności. Ten dokument to plan migracji — bez niego kolejne fazy są zgadywaniem.

Faza 2 — Zabezpieczenie testami

• Cel fazy: mieć siatkę bezpieczeństwa do weryfikacji masowych zmian. Kryterium odbioru: testy ścieżek krytycznych przechodzące na obecnej wersji PHP.

• 7. Wybierz ścieżki krytyczne — logowanie, rejestracja, zamówienie, płatność, generowanie dokumentów, najważniejsze integracje. Zwykle 5–8 przepływów.

• 8. Napisz testy charakterystyczne — testy utrwalające obecne zachowanie (także błędy). W starym kodzie nie testuj „jak powinno być", testuj „jak jest".

• 9. Przygotuj dane testowe — kopia produkcyjnej bazy (zanonimizowana) albo realistyczne fixtures. Migracja na pustej bazie nie wykryje problemów.

• 10. Uruchom testy na obecnej wersji — zielony stan wyjściowy to warunek. Jeśli testy nie przechodzą przed migracją, nie będą przechodzić po.

• 11. Dodaj testy do CI (jeśli jest) — testy muszą się uruchamiać automatycznie przy każdym commicie, na obu wersjach PHP (obecnej i docelowej).

• Kryterium odbioru: zestaw testów pokrywający ścieżki krytyczne, uruchamialny jedną komendą.

Faza 3 — Refaktoryzacja i poprawki

• Cel fazy: kod zgodny z docelową wersją PHP, zmiany podzielone na czytelne kroki. Kryterium odbioru: zielone testy i czysty PHPStan na docelowej wersji.

• 12. Skonfiguruj Rector — plik rector.php z withPhpSets dla docelowej wersji, ścieżkami do kodu i testów.

• 13. Uruchom Rector w trybie podglądu — --dry-run, przegląd zakresu zmian (mogą być tysiące linii).

• 14. Zastosuj zmiany krokiem wersji — dla dużych projektów: osobno 7.4 → 8.0, osobno 8.0 → 8.1 itd. Osobny commit na krok.

• 15. Uruchom testy po każdym kroku — regresja po konkretnym kroku jest łatwa do cofnięcia; po pięciu krokach naraz — trudna.

• 16. Popraw ręcznie to, czego automaty nie naprawiły — logika zależna od zmienionego zachowania (rzutowania, sortowanie, porównania stringów numerycznych).

• 17. Wymień porzucone biblioteki — każda wymiana to osobne zadanie z własnym testem; zaplanuj je na podstawie audytu z fazy 1.

• 18. Sformatuj kod — PHP-CS-Fixer albo Pint po masowych zmianach, żeby diffy były czytelne dla zespołu.

• 19. Wyzeruj deprecation warnings — uruchom aplikację na docelowej wersji i doprowadź logi do zera ostrzeżeń. Zostawione deprecation to lista zadań, która nie zniknie sama.

• Kryterium odbioru: kod na gałęzi migracyjnej przechodzi testy i PHPStan na docelowej wersji PHP, logi bez deprecation.

Faza 4 — Staging i wdrożenie

• Cel fazy: potwierdzona zgodność na środowisku lustrzanym wobec produkcji. Kryterium odbioru: staging działa stabilnie na docelowej wersji, plan wycofania gotowy.

• 20. Zbuduj staging na docelowej wersji PHP — z tymi samymi rozszerzeniami i konfiguracją (php.ini, OPcache) co produkcja.

• 21. Wgraj kopię danych produkcyjnych — z uwzględnieniem integracji: klucze API w trybie testowym, webhooki wyłączone albo przekierowane.

• 22. Przejdź testy manualne ścieżek krytycznych — testy automatyczne nie pokrywają wszystkiego, co widzi człowiek (podatności wizualne, edge case'y formularzy).

• 23. Sprawdź integracje zewnętrzne — płatności, kurierzy, marketplace, ERP: pełny przebieg transakcji testowej na każdym kanale.

• 24. Przygotuj plan wycofania — stara wersja PHP zostaje na serwerze; wiesz, jak w 5 minut wrócić (przełączenie wersji + ewentualny rollback kodu).

• 25. Zaplanuj okno wdrożenia — poza szczytem ruchu, z osobą dostępną po wdrożeniu. Wdrożenie w piątek po południu to antywzorzec.

• 26. Wdróż i obserwuj na żywo — logi błędów, czasy odpowiedzi, kolejki, płatności. Pierwsze 24–48 godzin to okres największej czujności.

• Kryterium odbioru: produkcja na docelowej wersji PHP, kluczowe metryki bez zmian albo lepsze, zero nowych błędów w logach.

Faza 5 — Stabilizacja i porządki

• Cel fazy: domknięcie migracji i przygotowanie gruntu pod kolejną. Kryterium odbioru: system stabilny przez 2–4 tygodnie, lista zaległości technicznych zaktualizowana.

• 27. Obserwuj logi przez 2–4 tygodnie — deprecation, wolne zapytania, błędy integracji. Nowe ostrzeżenia to zwykle miejsca, których testy nie pokryły.

• 28. Zaktualizuj zależności i framework — druga faza migracji: po stabilizacji PHP podnieś biblioteki i framework do docelowych wersji.

• 29. Włącz Rector do CI — krok rector process --dry-run w pipeline blokuje powrót starych wzorców w nowym kodzie.

• 30. Zaplanuj kolejną aktualizację — zapisz datę EOL docelowej wersji (np. 8.4 → 31.12.2028) i zaplanuj następną migrację na rok przed nią.

• Kryterium odbioru: migracja zamknięta, system na wspieranej wersji, kolejny krok zaplanowany z wyprzedzeniem.

Najczęstsze błędy, które ta checklista eliminuje

Doświadczenie z migracji pokazuje te same potknięcia w różnych projektach.

• Start bez audytu — „najwyżej poprawimy błędy, które wyskoczą". Efekt: migracja ciągnie się tygodniami, bo blokady wychodzą pojedynczo.
• Skok przez wszystkie wersje naraz — bez kroków pośrednich nie da się przypisać regresji do zmiany. Diagnoza zamiast godzin zajmuje dni.
• Brak testów i „ręczne klikanie" — weryfikacja manualna pokrywa 10% powierzchni. Reszta wyjdzie u użytkowników.
• Staging różny od produkcji — inne rozszerzenia, inny php.ini, brak OPcache. „U mnie działa" tuż przed awarią na produkcji.
• Wdrożenie bez planu wycofania — pierwszy poważny błąd bez drogi powrotnej oznacza przestój liczony w godzinach.
• Zapomniane zależności — migracja PHP bez aktualizacji bibliotek to połowa pracy; stara biblioteka na nowym PHP zwykle nie działa lepiej.

Pełny kontekst procesu — z opisem każdego etapu, narzędziami i kosztami — znajdziesz w przewodniku o migracji PHP na 8.x. Praktykę pracy z Rectorem opisuje artykuł o automatycznej migracji z Rector, a widełki budżetowe — artykuł o koszcie migracji PHP. Jeśli system działa na 8.2, sprawdź deadline w artykule o końcu wsparcia PHP 8.2.

Najczęściej zadawane pytania

Czy checklista migracji PHP sprawdza się w małych projektach?

Tak — w małych projektach część punktów zajmuje minuty (inwentaryzacja, audyt), a całość domyka się w kilka dni. Skaluj głębokość, nie pomijaj faz: nawet w małym projekcie kolejność „zmierz → zabezpiecz → przepisz → wdróż → obserwuj" chroni przed kosztownymi niespodziankami.

Ile punktów z checklisty wymaga programisty, a ile mogę zrobić sam?

Inwentaryzację (1, 5), kopie zapasowe i część weryfikacji manualnej (22, 23) zrobisz samodzielnie. Audyt zgodności, refaktoryzacja, testy i wdrożenie wymagają programisty. Jeśli prowadzisz migrację z wykonawcą, checklista służy do kontroli — pytaj o status każdej fazy i kryterium odbioru.

Kiedy powinienem zacząć migrację według tej checklisty?

• Odwrotnie od daty EOL: dla PHP 8.2 (EOL 31.12.2026) start najpóźniej w październiku–listopadzie, żeby mieć bufor na nieprzewidziane blokady. Zasada ogólna: zaczynaj planowanie rok przed EOL obecnej wersji, a wykonanie — pół roku przed.

Co, jeśli w trakcie migracji znajdę więcej blokad, niż pokazał audyt?

To normalne w projektach bez dokumentacji — audyt pokrywa większość, nie wszystko. Traktuj nowe blokady jak pozycje w planie: dopisz do listy, oceń pracochłonność, zdecyduj (naprawa vs wymiana vs wycięcie funkcji). Właśnie dlatego wdrożenie planuje się z buforem czasu, a nie „na styk" z EOL.

Czy migracja PHP wymaga też migracji bazy danych?

Zwykle nie — zmiana wersji PHP nie wymaga zmian w bazie. Wyjątki: porzucone biblioteki ORM mogą wymagać aktualizacji schematu, a kod używający usuniętych API bazodanowych (np. mysql_*) wymaga przepisania na PDO/mysqli. Migracja serwera bazy (np. MySQL 5.7 → 8.0) to osobny projekt — zaplanuj go świadomie, nie „przy okazji".

Jak udokumentować wykonaną migrację?

• Minimum: wersja startowa i docelowa PHP, lista wymienionych bibliotek, zakres zmian w kodzie (linki do commitów), wyniki testów, data wdrożenia i obserwacje po wdrożeniu. Dokument przyda się przy następnej migracji — i przy audytach bezpieczeństwa, które coraz częściej pytają o historię aktualizacji.

Źródła

• PHP.net — wspierane wersje
• PHP.net — instrukcje migracji między wersjami
• Rector — automatyczna refaktoryzacja
• PHPCompatibility — skan zgodności
• PHPStan — analiza statyczna