Hoe PHP-projecten statisch te analyseren met PHPStan

0
134

PHPStan is een statisch analysesysteem voor PHP-projecten. Het vindt bugs in uw codebase door de bronbestanden te inspecteren. U hoeft uw code niet uit te voeren of handmatig tests te schrijven om problemen te ontdekken!

De term “statische analyse” wordt gedefinieerd als foutopsporingscode zonder deze daadwerkelijk uit te voeren. Het wordt het vaakst gebruikt met geïnterpreteerde talen, zoals PHP, omdat de problemen die het vindt de neiging hebben om naar boven te komen in de compilatiefase in gecompileerde talen.

Statische analyse geeft meestal de beste resultaten wanneer het wordt uitgevoerd binnen een goed gestructureerde, sterk getypte codebase. De documentatie van PHPStan geeft aan dat “moderne objectgeoriënteerde code” heeft hier het meeste baat bij, aangezien deze projecten PHPStan meer informatie geven om mee te werken.

PHPStan aan uw project toevoegen

Om PHPStan uit te voeren, moet u PHP 7.1 of nieuwer hebben. Deze vereiste is alleen van toepassing op de versie van PHP die wordt gebruikt om PHPStan zelf uit te voeren. De tool kan bronbestanden analyseren die gericht zijn op oudere versies van PHP.

Het wordt aanbevolen om Composer te gebruiken om PHPStan als afhankelijkheid toe te voegen:

composer required –dev phpstan/phpstan

Het binaire bestand PHPStan wordt aan uw project toegevoegd op vendor/bin/phpstan. Je kunt het nu gebruiken om je codebase voor de eerste keer te analyseren:

vendor/bin/phpstan analysis src

Het hierboven getoonde commando zal PHPStan's tests uitvoeren op alle bronbestanden in je src directory. Afhankelijk van de grootte van uw codebase, kan dit enkele minuten duren.

< /p>

U ziet een groene “[OK] Geen fouten” bericht als alle tests slagen. Anders wordt de lijst met gevonden fouten weergegeven. Volg de getoonde richtlijnen om elke fout op te lossen voordat u PHPStan opnieuw uitvoert.

Fouttypen en -niveaus

PHPStan bevat een overvloed aan controles voor een breed scala aan mogelijke codebase-problemen. Enkele van de meest voorkomende problemen die u tegenkomt, zijn de volgende:

  • Type systeemproblemen– Een getypte eigenschap een ongeldige waarde toewijzen of onjuist getypte parameters doorgeven aan een methode. Dit omvat ook contractproblemen, zoals een klasse die een interface onjuist implementeert.
  • Functie-aanroepen – Te veel of te weinig parameters doorgeven bij het aanroepen van een functie of methode (bijvoorbeeld 3 in plaats van 4).
  • Onbekende klassen, methoden en functies – Proberen iets te gebruiken dat niet in de codebase bestaat.
  • Toegang tot ongedefinieerde/mogelijk ongedefinieerde variabelen– Proberen een variabele te gebruiken die niet in een bepaald bereik is gedefinieerd, of die niet altijd een waarde heeft, maar wordt gebruikt in een context waarin dat wel wordt aangenomen.
  • Controle op dode code – Markering van nutteloze code, zoals booleaanse vergelijkingen die altijd naar dezelfde waarde worden omgezet en codevertakkingen die nooit worden uitgevoerd (bijv. code die volgt op een return-statement binnen functies).

Regels zijn gesorteerd in 9 verschillende “niveaus”, gelabeld van 0 tot 8. Het speciale niveau max fungeert als een alias voor het hoogst mogelijke niveau. Na verloop van tijd kan PHPStan extra numerieke niveaus toevoegen, dus het gebruik van max zorgt ervoor dat u altijd de strengst mogelijke controles krijgt.

Standaard voert PHPStan niveau 0 uit. Dit omvat alleen de meest fundamentele tests. Het is een goed idee om uw codebase elk niveau afzonderlijk te laten passeren voordat u doorgaat naar het volgende. Volwassen projecten zullen waarschijnlijk bij elk nieuw niveau weer andere problemen tegenkomen.

Advertentie

Om het niveau dat PHPStan gebruikt te wijzigen, kunt u de –level opdrachtregelparameter doorgeven:

vendor/bin/phpstan analysis src –level 8

Naast de ingebouwde checks, PHPStan-extensies zijn beschikbaar om nog meer functionaliteit toe te voegen. U kunt ook uw eigen regels vanaf het begin schrijven. Dit is handig wanneer u functionaliteit afschaft die ontwikkelaars niet langer in nieuwe code zouden moeten gebruiken. We zullen het maken van aangepaste regels in een toekomstig artikel bespreken.

PHPStan configureren

Naast de eerste experimenten, kan het gebruik van de opdrachtregelinterface van PHPStan snel vermoeiend worden. Het is het beste om een ​​configuratiebestand aan uw project toe te voegen, dat vervolgens kan worden vastgelegd voor bronbeheer dat al uw ontwikkelaars kunnen gebruiken.

PHPStan gebruikt het Neon-configuratiebestandsformaat, dat een syntaxis heeft die erg lijkt op YAML. Maak een phpstan.neon-bestand in de hoofdmap van uw project. Dit bestand wordt automatisch geladen wanneer PHPStan start, dus u kunt nu het analyse-commando uitvoeren zonder verdere argumenten:

vendor/bin/phpstan analysis

Om het gebruikte configuratiebestand te negeren, geeft u de –configuration-vlag door :

vendor/bin/phpstan analysis –configuration /phpstan-config.neon

Je moet nu je phpstan.neon-bestand vullen met wat inhoud. Een goed startpunt kan er als volgt uitzien:

parameters: level: 0 paths: – src Advertisement

Dit basisconfiguratiebestand zou dezelfde uitvoer moeten geven als de eerder getoonde opdrachtregelaanroep. U kunt extra mappen toevoegen om te scannen als nieuwe regels in de sectie paden. Als u bestanden en mappen wilt uitsluiten, voegt u ze toe aan een Excludes_analyse-blad in dezelfde sectie met parameters.

Fouten negeren

Af en toe kan PHPStan een probleem aan het licht brengen dat onvermijdelijk. Als er een probleem is dat u niet meteen kunt oplossen, wilt u dit misschien expliciet negeren om de tests te laten slagen.

Dit is met name belangrijk wanneer u naar een ander controleniveau wilt gaan, of als u PHPStan gebruikt in een CI-omgeving waar een mislukte uitvoering de implementatie van uw build stopt. Toch moet u deze handelwijze niet lichtvaardig opvatten – je moet er alleen voor kiezen om een ​​gerapporteerde fout te negeren als je zeker weet dat het veilig is om dit te doen.

Zodra je de beslissing hebt genomen, voeg je een nieuwe negeerErrors-sectie toe binnen de parameters van je configuratiebestand. U moet het bericht definiëren dat moet overeenkomen, als een regex, en de paden waarop de uitsluiting moet worden toegepast:

parameters: niveau: 0 paden: – src negeerErrors: – bericht: '/Return type tekenreeks van methode VoorbeeldClass:: voorbeeld() is niet covariant(.*).' path: src/ExampleClass.php

U kunt optioneel paden specificeren als een array van paden, ter vervanging van de hierboven getoonde enkele padsleutel.

Optionele regels

< p>De strengheid van PHPStan kan worden aangepast door een reeks configuratievariabelen. Hiermee kunt u de uitgevoerde controles verfijnen, buiten het hierboven beschreven niveaussysteem. Sommige hiervan zijn potentieel controversieel of passen waarschijnlijk niet bij alle privéstijlgidsen, daarom zijn ze standaard uitgeschakeld.

Een paar instellingen die de moeite waard kunnen zijn om in te schakelen, zijn onder meer:

  • checkAlwaysTrueInstanceof&8211; Markeert gebruik van instanties waarvan altijd waar zal worden geëvalueerd.
  • checkAlwaysTrueStrictComparison – Markeert wanneer een uitdrukking die === of !== gebruikt, altijd waar zal zijn.
  • checkFunctieNaamCase – Zorgt ervoor dat de hoofdletters van functienamen overeenkomen met hun definitie wanneer ze door de hele codebase worden aangeroepen.
  • polluteScopeWithLoopInitialAssignments – Indien ingesteld op false (het is standaard true), kunnen variabelen die zijn gedeclareerd in initiële lusinstructies (bijv. $i in $for ($i = 1; $i < 10; $i++)) niet van buitenaf worden benaderd het codeblok van de lus, waardoor mogelijke vervuiling van de bovenliggende scope wordt vermeden.
  • rapportStaticMethodSignatures – Dwingt volledige typecontrole af voor parameters en retourtypen in statische methoden wanneer deze worden overschreven door een onderliggende klasse.

Advertentie

Volledige details over deze optionele instellingen – en nog veel meer – kan worden gevonden in de configuratiereferentie van PHPStan.

Conclusie

Dat is het einde van onze inleiding tot PHPStan. Het helpt je vertrouwen te hebben in je codebase en markeert mogelijke problemen voordat ze een probleem worden in de productie.

PHPSan is zo snel in te stellen dat er geen enkele reden is om het niet te gebruiken, vooral niet als je aan het werk bent met een moderne sterk getypte codebase. Laat u echter niet misleiden door te denken dat het handmatige tests kan vervangen. PHPStan kan bogen op een groot assortiment aan controles, maar het kan geen logische problemen identificeren en begrijpt de bedrijfsregels van uw project niet. Het is slechts een extra troef in uw gereedschapskist bij het beoordelen van de gezondheid van een codebase, naast vertrouwde metgezellen zoals unit-tests en end-to-end functionaliteitstests.