PHP Code Sniffer – Parameter und eigene Regelsets (Standard)

Gestern hatten wir über die Installation und die erste Verwendung des PHP Code Sniffers (PCS) geredet. Heute werde ich noch ein wenig über die Parameter reden, die ich gestern noch nicht angesprochen habe, die aber trotzdem wichtig sind. Im zweiten Teil geht es dann um Regelsets. Wir werden lernen, wie man vorhandene Regeln zu seinem eigenen Set kombiniert.

PHP Code Sniffer Parameter

Zwei wichtige Parameter hatten wir ja gestern bereits erklärt, v für verbose und --standard für die Wahl der Standards. Hier aber die Liste der weiteren Parameter.

• --extensions
  Mit diesem Parameter definieren wir, welche Endungen wir durch den Sniffer jagen wollen. Da wir PCS auch auf komplette Verzeichnisse loslassen können kann dies ganz nützlich sein. Interessant ist vielleicht auch zu wissen, dass der Sniffer auf JavaScript Dateien untersuchen kann. Leider hat dieses Feature bei unsere Projekten immer zu Problemen geführt und aus diesem Grund haben wir hier auch nur .php Dateien erlaubt, denn in der Standard Einstellung werden auch .js Dateien kontrolliert. Natürlich sollte es auch einen Zeitgewinn bringen, falls man nur PHP Regeln definiert hat und er die .js Datein trotzdem syntaktisch auseinander nimmt.
  Beispiel: --extension php,js
• --report
  Wenn wir das Tool über die Kommandozeile händisch aufrufen, dann sollte uns dieser Parameter nicht so wichtig vorkommen. In der Kombination mit PhpUnderControl ist er jedoch sehr hilfreich. Vielleicht noch so am Rande: wählt man als report Typ „checkstyle“, so werden Logfiles produziert, die identisch mit denen sind, die vom Java Tool Checkstyle produziert werden. Wie ich finde ziemlich praktisch, da ich so alle Auswertetools für Checkstyle auch auf meine PHP Ergenisse anwenden kann.
  Beispiel: --report checkstyle
• --ignore
  Natürlich will man nicht immer alle Dateien, die in einem bestimmten Verzeichnis sind überprüfen. Third Party Code sollte in den meisten Fällen nicht mitgetestet werden. Aus diesem Grund gibt es den ignore Parameter, mit dem man definieren kann, was ignoriert werden soll. Der Parameter nimmt als Werte Komma separierte „Patterns“ an.
  Beispiel: --ignore lib/*,*/tests/*, diese Einstellung würde das Verzeichnis lib komplett außen vor lassen, genau so wie alle tests Unterverzeichnisse, egal wo diese sich befinden.

Ich denke fürs erste sollten diese Parameter reichen, um den Einstieg in PCS zu schaffen. Wer weitere Beispiel nützlich findet, der sollte sich die Projektseite noch einmal genauer ansehen.

Regelsets zusammenstellen

Nachdem wir nun wissen, wie wir bereits existierende Standards einbinden und sie über die Kommandozeile auch aufrufen können, wollen wir jetzt unsere eigenen Sets zusammenstellen. Da dies am einfachsten an einem Beispiel zu erläutern ist, nutzen wir doch das Zend Regelset um es mal genauer zu betrachten. Dieses sollte sich in folgendem Verzeichnis befinden:

/usr/share/php/PHP/CodeSniffer/Standards/Zend/ZendCodingStandard.php

Der Inhalt, zumindest unter der Code Sniffer Version 1.2.0a1 sollte wie folgt aussehen:

class PHP_CodeSniffer_Standards_Zend_ZendCodingStandard extends PHP_CodeSniffer_Standards_CodingStandard
{
    public function getIncludedSniffs()
    {
        return array(
                'Generic/Sniffs/Functions/OpeningFunctionBraceBsdAllmanSniff.php',
                'Generic/Sniffs/PHP/DisallowShortOpenTagSniff.php',
                'Generic/Sniffs/WhiteSpace/DisallowTabIndentSniff.php',
                'PEAR/Sniffs/Classes/ClassDeclarationSniff.php',
                'PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php',
                'PEAR/Sniffs/Files/LineEndingsSniff.php',
                'PEAR/Sniffs/Functions/FunctionCallArgumentSpacingSniff.php',
                'PEAR/Sniffs/Functions/FunctionCallSignatureSniff.php',
                'PEAR/Sniffs/Functions/ValidDefaultValueSniff.php',
                'PEAR/Sniffs/WhiteSpace/ScopeClosingBraceSniff.php',
                'Squiz/Sniffs/Functions/GlobalFunctionSniff.php',
               );
    }
}

Ich war mal so frei und habe den ganzen Kommentar Teil weggelassen. Wenn ihr aber die ganze Datei sehen wollt, dann habe ich sie für euch hier hoch geladen. Betrachtet man die Klasse, so ist das einzige, was sie macht einen Array zurück zu liefern, der alle Regeln, sogenannte Sniffs, beinhaltet. Die Pfade sind hierbei relativ zum Standards Verzeichnis zu sehen.

Damit wir unseren eigenen Standard definieren können erstellen wir erst mal im Standards Verzeichnis unser Unterverzeichnis PhpHatesMe und kopieren dort den Zend Standard als PhpHatesMeCodingStandard.php rein. Jetzt passen wir noch Klassennamen (PHP_CodeSniffer_Standards_PhpHatesMe_PhpHatesMeCodingStandard) an und fertig ist unser eigenes Set. Wie immer habe ich es auch schon vorbereitet. Prinzipiell können wir unseren Standard jetzt auch schon verwenden.

phpcs --standard=PhpHatesMe badClass.php

Der Output ist wie erwartet:

FILE: /var/www/phpcodesniffer/badClass.php
--------------------------------------------------------------------------------
FOUND 4 ERROR(S) AND 0 WARNING(S) AFFECTING 4 LINE(S)
--------------------------------------------------------------------------------
  5 | ERROR | Spaces must be used to indent lines; tabs are not allowed
  7 | ERROR | Spaces must be used to indent lines; tabs are not allowed
  8 | ERROR | Spaces must be used to indent lines; tabs are not allowed
 10 | ERROR | Spaces must be used to indent lines; tabs are not allowed
--------------------------------------------------------------------------------

Jetzt liegt es an euch. Es gibt ca. 160 vordefinierte Regeln, die ich ausprobieren könnt. Für die, die nicht so firm sind mit Linux, hier der Befehl, wie ihr euch alle auflisten lassen könnt: find -iname '*Sniff.php'. In den meisten Fällen sind die Namen ja schon relativ selbstredend. Wer aber genau wissen will, was ein Sniff so alles treibt, der kann sich die gute PHPDoc Dokumentation anschauen, die in jedem File vorhanden ist. Die Zusammenfassung dazu findet ihr aber auch auf der PEAR Doku Seite.

Falls jemand eine gute Seite kennt, auf der näher auf die einzelnen Regeln eingegangen wird, dann kann er mir diese gerne nennen. Ich werde sie dann nennen.

Morgen kommt der komplexeste Teil der Reihe: eigene Regeln schreiben. Da dies der Teil ist, den ich selbst noch nie gemacht habe, wird es ein sehr spannendes Kapitel … auch und besonders für mich.