Hogyan lehet statikusan elemezni a PHP-projekteket a PHPStan segítségével – CloudSavvy IT

PHPStan egy statikus elemzési rendszer a PHP projektekhez. A forrásfájlok vizsgálatával hibákat talál a kódbázisában. A problémák felfedezéséhez nem kell futtatnia a kódot vagy manuálisan teszteket írni!

A „statikus elemzés” kifejezést hibakeresési kódként definiálják anélkül, hogy azt ténylegesen végrehajtanák. Leggyakrabban értelmezett nyelveknél, például a PHP-nél használják, mivel az általa talált kérdések az összeállított nyelvek fordítási szakaszában szoktak megjelenni.

A statikus elemzés akkor működik a legjobban, ha jól strukturált, erősen tipizált kódalapon fut. Ez különösen fontos a PHPStan esetében, mivel ez technikailag hibrid elemző eszköz.

A statikus elemzés definíciójával ellentétben A PHPStan valóban betöltődik és futtassa a forrásfájlokat. Ennek oka, hogy részben felhasználja a PHP-ket beépített introspektív képességek elemezni a projektjét.

Következésképpen a szkript gyökerében található mellékhatások végrehajtódnak:

function example() : void {
    echo "Example output";
}
 
example();

Ha a PHPStan elemezné a fent bemutatott fájlt, megfigyelheti Example output kibocsátása a konzolra. Ezért a legjobb, ha a PHPStant olyan inert forrásfájlok ellen futtatja (amelyek csak osztályokat és funkciókat tartalmaznak), amelyek betöltéskor nem mutatnak mellékhatásokat.

PHPStan hozzáadása a projekthez

A PHPStan futtatásához PHP 7.1 vagy újabb szükséges. Ez a követelmény csak a PHP azon verziójára vonatkozik, amelyet a PHPStan végrehajtására használnak. Az eszköz képes elemezni a PHP régebbi verzióit megcélzó forrásfájlokat.

Javasoljuk, hogy használja a Composer programot a PHPStan hozzáadásához függőségként:

composer require --dev phpstan/phpstan

A PHPStan bináris fájl hozzáadódik a projektjéhez a következő címen: vendor/bin/phpstan. Mostantól a kódbázis első elemzésére használhatja:

vendor/bin/phpstan analyse src

A fent bemutatott parancs futtatja a PHPStan tesztjeit az Ön összes forrásfájljával szemben src Könyvtár. A kódbázis méretétől függően ez néhány percet igénybe vehet.

Látni fog egy zöld színt[OK] Nincs hiba ”üzenet, ha az összes teszt sikeres. Ellenkező esetben megjelenik a felmerült hibák listája. Kövesse a bemutatott útmutatást az egyes hibák megoldásához, mielőtt újra futtatná a PHPStan-t.

Hiba típusok és szintek

A PHPStan rengeteg ellenőrzést tartalmaz, amelyek a lehetséges kódbázisok sokféle kérdésére kiterjednek. A leggyakoribbak a következők:

• Írja be a rendszer problémáit – Gépelt tulajdonság hozzárendelése érvénytelen értékhez, vagy helytelenül beírt paraméterek átadása egy metódushoz. Ide tartoznak a szerződéses kérdések is, például egy osztály, amely helytelenül valósítja meg az interfészt.
• Funkcióhívások – Túl sok, vagy nem elég paraméter átadása egy funkció vagy módszer meghívásakor (pl. 4 helyett 3).
• Ismeretlen osztályok, módszerek és funkciók – Olyat próbál használni, amely nem létezik a kódbázisban.
• Hozzáférés nem definiált / lehetséges undefined változókhoz – Megpróbál olyan változót használni, amely nincs meghatározva egy adott hatókörben, vagy amelynek nem mindig van értéke, de olyan kontextusban használják, ahol feltételezik.
• Holt kód ellenőrzése – Haszontalan kód megjelölése, például logikai összehasonlítások, amelyek mindig ugyanazon értéket adják meg, és olyan kódágak, amelyek soha nem kerülnek végrehajtásra (pl. return függvényeken belüli utasítás).

A szabályokat 9 különböző „szintre” rendezzük, 0-tól 8-ig címkézve. A speciális szint max a lehető legmagasabb szintű álnévként működik. Idővel a PHPStan további numerikus szinteket adhat hozzá, így használva max biztosítja, hogy mindig a lehető legszigorúbb ellenőrzéseket kapja meg.

Alapértelmezés szerint a PHPStan végrehajtja a 0. szintet. Ez csak a legalapvetőbb teszteket tartalmazza. Célszerű, ha a kódbázis minden szintet külön-külön halad át, mielőtt továbblép a következő szintre. A kiforrott projektek valószínűleg minden új szintnél újabb kérdéssorba ütköznek.

A PHPStan által használt szint megváltoztatásához átadhatja a --level parancssori paraméter:

vendor/bin/phpstan analyse src --level 8

A beépített ellenőrzések mellett a PHPStan kiterjesztések is elérhetők a még nagyobb funkcionalitás érdekében. Saját szabályokat is írhat a semmiből. Ez akkor hasznos, ha megszűnik azok a funkciók, amelyeket a fejlesztők már nem használhatnak új kódokban. Az egyedi szabályok létrehozásáról egy későbbi cikkben foglalkozunk.

A PHPStan beállítása

A kezdeti kísérleteken túl a PHPStan parancssori felületének használata gyorsan fárasztóvá válhat. A legjobb, ha hozzáad egy konfigurációs fájlt a projektjéhez, amelyet elkötelezhet a forrásellenőrzés mellett, amelyet az összes fejlesztő használhat.

A PHPStan a Neon konfigurációs fájlformátum, amelynek szintaxisa nagyon hasonló a YAML-hez. Hozzon létre egy phpstan.neon fájlt a projekt gyökérkönyvtárában. Ez a fájl automatikusan betöltődik, amikor a PHPStan elindul, így most futtathatja a analyse parancs további érvek nélkül:

vendor/bin/phpstan analyse

A használt konfigurációs fájl felülbírálásához adja át a --configuration zászló:

vendor/bin/phpstan analyse --configuration /phpstan-config.neon

Most be kell töltenie a phpstan.neon fájl tartalommal. Egy jó kiindulópont így nézhet ki:

parameters:
  level: 0
  paths:
    - src

Ennek az alapkonfigurációs fájlnak ugyanazt a kimenetet kell adnia, mint a korábban bemutatott parancssori meghívás. Felvehet további könyvtárakat, amelyek új sorként szkennelhetők a paths szakasz. A fájlok és könyvtárak kizárásához vegye fel őket egy excludes_analyse levél ugyanazon belül parameters szakasz.

A hibák figyelmen kívül hagyása

Esetenként a PHPStan elkerülhetetlen problémát vet fel. Ha olyan probléma merül fel, amelyet nem tud azonnal megoldani, érdemes ezt kifejezetten figyelmen kívül hagynia, hogy a tesztek sikeresek legyenek.

Ez különösen fontos, ha fel akar lépni az ellenőrzések egy másik szintjére, vagy ha a PHPStant olyan CI környezetben használja, ahol a sikertelen futtatás leállítja a build telepítését. Ennek ellenére ne vegye könnyedén ezt a cselekvési irányt – csak akkor válassza a bejelentett hiba figyelmen kívül hagyását, ha biztos benne, hogy ezt biztonságosan megteheti.

Miután meghozta a döntést, adjon hozzá egy újat ignoreErrors szakasz a parameters konfigurációs fájljának. Meg kell határoznia az üzenetet, hogy illeszkedjen, mint regex, és a kizárás alkalmazásához szükséges utakat:

parameters:
  level: 0
  paths:
    - src
  ignoreErrors:
    - message: '/Return type string of method ExampleClass::example() is not covariant(.*).'
      path: src/ExampleClass.php

Opcionálisan megadhatja paths utak tömbjeként, felváltva a kislemezt path fent látható billentyűt.

Opcionális szabályok

A PHPStan szigorúságát konfigurációs változók sorozatával lehet beállítani. Ezek lehetővé teszik az elvégzett ellenőrzések finomhangolását a fent leírt szintrendszeren kívül. Ezek egy része potenciálisan ellentmondásos, vagy nem valószínű, hogy igazodna az összes privát stílusú útmutatóhoz, ezért alapértelmezés szerint ki vannak kapcsolva.

Néhány olyan beállítás, amelyet érdemes lehet engedélyezni:

• checkAlwaysTrueInstanceof – Megjelöli a instanceof amely mindig értékelni fogja true.
• checkAlwaysTrueStrictComparison – Megjelöli, ha egy kifejezés használ === vagy !== mindig értékelni fog true.
• checkFunctionNameCase – Biztosítja, hogy a függvénynevek nagybetűk megfeleljenek a definíciójuknak, amikor a kódbázisban meghívják őket.
• polluteScopeWithLoopInitialAssignments – Ha beállítása false (ez van true alapértelmezés szerint), a kezdeti ciklus utasításokban deklarált változók (pl $i ban ben $for ($i = 1; $i < 10; $i++)) megakadályozzák a hurok kódblokkján kívüli hozzáférést, elkerülve a szülő hatókörének lehetséges szennyezését.
• reportStaticMethodSignatures – Végrehajtja a paraméterek és a visszatérési típusok teljes típusellenőrzését statikus módszerekben, ha egy gyermekosztály felülírja őket.

Ezekről az opcionális beállításokról – és még sok minden másról – további részletek megtalálhatók a PHPStan oldalán konfigurációs hivatkozás.

Következtetés

Ezzel vége a bevezetésünknek PHPStan. Segít abban, hogy bízzon a kódbázisában, és rávilágít a lehetséges problémákra, még mielőtt azok problémává válnának a gyártásban.

A PHPStan olyan gyorsan telepíthető, hogy nincs oka annak, hogy ne használja, különösen akkor, ha modern, erősen tipizált kódbázissal dolgozik. Nem szabad azonban becsapni, hogy ez helyettesítheti a kézi tesztelést. A PHPStan sokféle ellenőrzéssel büszkélkedhet, de nem képes azonosítani a logikai kérdéseket, és nem érti a projekt üzleti szabályait. Ez csupán egy újabb eszköz az eszköztáradban, amikor egy kódbázis állapotát értékelik, és megbízható kísérők mellett szolgál, például egységtesztekkel és end-to-end funkcionalitási tesztekkel.