Jan Mikoláš
Praktický návod
Jak zavést PHPStan do existujícího projektu
Zastav přibývání nových typových chyb hned a existující dluh zmenšuj měřitelně po částech.
Nejdřív stručně
První cíl není nula chyb za jeden den
PHPStan může analyzovat starý projekt postupně. Nejdřív oprav špatný bootstrap, neznámé symboly a chyby v dotčené oblasti, potom případný zbytek uzamkni baseline souborem.
Baseline není odpadkový koš. Umožní CI blokovat nové problémy na přísném rule levelu, zatímco počet starých výjimek plánovaně klesá.
Připrav si
Zmapuj skutečný runtime projektu
Analýza musí znát stejné PHP, frameworkové typy a generovaný kód jako aplikace.
- Podporovanou verzi PHP a aktuální composer.lock spustitelné v lokálním i CI prostředí.
- Adresáře vlastního kódu a testů; vendor ani cache se přímo neanalyzují.
- Framework extension nebo bootstrapFiles pouze tam, kde jsou symboly vytvářené dynamicky.
- Člověka zodpovědného za revizi ignore pravidel, baseline a pravidelné zvýšení přísnosti.
Kroky 1 až 3
Zapoj analýzu bez velkého třesku
Nejdřív stabilizuj konfiguraci a signál, potom teprve řeš objem nálezů.
1. Nainstaluj a nakonfiguruj jednu cestu
- Nainstaluj nástroj do dev dependencies a commitni jeho verzi přes composer.lock.
- V phpstan.neon.dist nastav paths na vlastní src a případně tests, PHP version a konkrétní rule level.
- Spouštěj PHPStan ve stejném kontejneru nebo image jako aplikaci. Nejprve oprav class-not-found, bootstrap a chybné extension konfigurace.
- Přidej Composer script, aby vývojář i CI používali stejný příkaz bez skrytých lokálních argumentů.
composer require --dev phpstan/phpstan2. Oprav typy podle hodnoty
- Začni chybami, které mohou změnit runtime: špatné argumenty, nullable hodnoty, neexistující metody, unreachable větve a neúplné match.
- Přidej nativní typy na vstupy, návraty a properties. PHPDoc používej pro generika, array shapes a typy, které PHP neumí vyjádřit.
- Dynamická data z requestu, JSONu nebo databáze validuj na hranici a převáděj na DTO či value object.
- Neumlčuj problém širokým mixed nebo blanket ignore. Extension, stub nebo úzký ignore s identifikátorem použij jen pro prokazatelně bezpečnou dynamiku.
vendor/bin/phpstan analyse --memory-limit=1G3. Uzamkni starý dluh baseline
- Zvol co nejvyšší praktický level. Pokud zbývají desítky až stovky starých nálezů, vygeneruj jednorázový baseline a ručně ho zkontroluj.
- Baseline commitni, zahrň v konfiguraci a v CI zakaž nové chyby. Při běžné změně ho celý neregeneruj.
- Každý opravený soubor odstraní odpovídající výjimku. Sleduj počet baseline položek jako klesající metriku.
- Přísnost zvyšuj po modulech nebo úrovních; nový kód drž na aktuálním standardu bez přidávání historického dluhu.
vendor/bin/phpstan analyse --level=7 --generate-baselineKrok 4
Dokaž, že nové chyby neprojdou
Stejný příkaz musí být reprodukovatelný lokálně i na čistém CI runneru.
-
Spusť analýzu dvakrát
Oba běhy skončí se stejným výsledkem a konfigurace nezávisí na lokálně generovaném souboru.
composer phpstan -
Vlož úmyslnou typovou chybu
CI ji odmítne, i když je ve stejném souboru jako baselinované staré nálezy. Potom změnu vrať.
-
Oprav jednu baseline položku
PHPStan oznámí nepoužitý ignore nebo baseline upravíš cíleně; celkový počet výjimek klesne.
Když to zlobí
Nejčastější chyby
První běh hlásí tisíce neznámých tříd
Nejdřív oprav autoload, framework extension, generated stubs a paths. Baseline z chybné konfigurace negeneruj.
composer dump-autoloadBaseline při každém PR roste
Generování není běžný CI krok. Commitni pevný baseline a každou novou výjimku vyžaduj samostatně zdůvodnit.
Vývojář má jiný výsledek než CI
Sjednoť PHP image, extensions, composer.lock, config cestu a pracovní adresář. Cache nesmí měnit obsah výsledku.
Paměť analýzy rychle roste
Neanalyzuj vendor a cache, aktualizuj extensions a prozkoumej problematické soubory; vyšší limit je až poslední krok.
Hotovo
Statická analýza brání novému dluhu.
Konfigurace je reprodukovatelná, CI zachytí nové typové chyby a kontrolovaný baseline umožňuje staré nálezy postupně odstranit.