Heute möchte ich die kleine Artikelreihe zu den WordPress Coding Standards abschließen. Im letzten Kapitel soll es darum gehen, wie man die Überprüfung durch den PHP_CodeSniffer an die eigenen Anforderungen im Projekt anpassen kann.

Fehler direkt im Code ignorieren lassen

Manche Funktionen oder Konstrukte von WordPress können potentielle Sicherheitslücken sein. In solchen Fällen warnen euch die „Sniffs“ für die WordPress Coding Standards vor solchen möglichen Sicherheitslücken. So muss beispielsweise jede Ausgabe geschützt werden. Nun gibt es aber Funktionen, die man nicht „schützen“ kann, also mit einer speziellen Funktion kombinieren kann. Sehen wir uns mal zwei Codezeilen an, bei der eine umgeschrieben werden kann, eine aber nicht:

<?php _e( 'Select taxonomy', 'textdomain' ); ?>
<?php wp_dropdown_pages( $args ); ?>

Führen wir den CodeSniffer aus erhalten wir für diese beiden Zeilen folgende Fehlermeldungen:

----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
 17 | ERROR | Expected next thing to be an escaping function (like
    |       | esc_html_e() or esc_attr_e()), not '_e'
 18 | ERROR | Expected next thing to be an escaping function (see
    |       | Codex for 'Data Validation'), not '$args'
----------------------------------------------------------------------

Beide zeigen eine ähnliche Fehlermeldung. Es wird hier angemerkt, dass die Ausgabe eine Escaping-Funktion verwenden soll. Für die erste Zeile gibt es zwei mögliche Lösungen, dem zu entsprechen. Die bessere wird auch gleich vorgeschlagen. Hier die möglichen Lösungen:

<?php echo esc_html( __( 'Select taxonomy', 'textdomain' ) ); // sicher ?>
<?php echo esc_html_e( 'Select taxonomy', 'textdomain' ); // besser ?>

Bei der zweiten Codezeile haben wir aber ein größeres Problem. Denn die Funktion wp_dropdown_pages() gibt ja HTML-Code zurück. Diesen können wir nicht einfach schützen. Wieso aber warnt uns der Sniffer davor? In den Argumenten kann man wiederum HTML-Code verwenden, der direkt ohne weiteres Escaping ausgegeben wird. Hier kann es also zu der Sicherheitslücke kommen.

Wie aber können wir dennoch eine „OK“ für unseren Code bekommen, wenn wir sicher sind, dass es sich um keinen Fehler handelt. Die Antwort daraus sind spezielle Kommentare, mit denen man bestimmte Zeilen und Fehler „whitelisten“ kann. Diese Kommentare sind im Wiki zu den WordPress Coding Standards beschrieben. Für unseren Code sieht das wie folgt aus:

<?php wp_dropdown_pages( $args ); // WPCS: XSS ok. ?>

Wir haben also angegeben, dass wir uns der Gefahr einer Cross-Site-Scripting-Attacke bewusst sind und dass wir unseren Code dahingehend anderweitig abgesichert haben. Der Sniffer ignoriert dann also diesen Fehler.

Fehler generell ignorieren

Manche Fehler möchte man aber nicht pro Zeile ignorieren lassen, sondern global für alle Dateien. Oder aber es sind Fehler, die man nicht als Kommentar ignorieren lassen kann, weil sie sich z.B. auf den Dateinamen oder Dateieigenschaften beziehen. Dann muss ein anderer Lösungsweg gewählt werden.

Erstellen eines PHP_CodeSniffer Rulesets

Für den PHP_CodeSniffer kann man sogenannte Rulesets definieren. Diese werden in einer „ruleset.xml“ Datei definiert und geben an, welcher Coding Standard verwendet werden soll, welche Ordner ausgeschlossen werden sollen und welche Regeln man ausschließen möchte. Hier ein Beispiel für eine solche Datei:

<?xml version="1.0"?>
<ruleset name="Project">
	<exclude-pattern>*/themes/twenty*</exclude-pattern>
	<exclude-pattern>*.min.*</exclude-pattern>
	<rule ref="WordPress">
		<exclude name="Generic.Files.LineEndings" />
		<exclude name="WordPress.Files.FileName" />
		<exclude name="WordPress.VIP.RestrictedFunctions" />
		<exclude name="WordPress.VIP.PostsPerPage" />
	</rule>
</ruleset>

Mit den „exclude-pattern“ Knoten können wir bestimmte Ordner und Dateien ausschließen. Hier im Beispiel werden die Default-Themes und alle minifizierten Dateien ausgeschlossen. Anschließend definiert die Datei, welcher Coding Standard als Basis verwendet werden soll. Ich habe hier den sehr strikten „WordPress“ Standard gewählt.

Innerhalb des Knotens habe ich einige Regeln ausgeschlossen. Die erste Regel ist eine generische, die definiert, dass nur Unix-Newlines verwendet werden dürfen. Das ist im Allgemeinen eine sehr gute Idee. Wenn man aber in einem Team arbeitet und einige Nutzer Windows verwenden, dann checkt Git in der Regel alle Dateien mit den nativen Zeilenenden aus. Hier würden also fast alle Dateien jede Zeile als Fehler markieren.

Die zweite Ausnahme kümmert sich um Dateinamen in Themes. Laut Regel sollen Dateien nur Bindestriche verwenden. Hat man aber eine Template-Datei für einen Custom Post Type, der einen Unterstrich enthält, dann bricht man diese Regel (und muss es auch). Daher lasse ich auch diese Regel ignorieren. Die anderen beiden Regeln sind im „WordPress-VIP“ Coding Standard definiert.

Um das Ruleset zu verwenden gebt ihr den Pfad zur Datei anstelle des Namens eines installieren Coding Standards an:

phpcs --standard=ruleset.xml wp-content

Ich denke das Konzept ist klargeworden. Welche Namen die „Sniffs“ haben müsst ihr im Quellcode der WordPress Coding Standards nachsehen. Eine Liste aller Sniffs habe ich bisher leider nicht gefunden.

Fazit

Hiermit möchte ich meine kleine Artikelreihe zu den WordPress Coding Standards abschließen. Ich hoffe ich konnte euch zeigen, wieso ihr die Standards bei euren zukünftigen Projekten unbedingt einsetzen solltet, wie euch eine IDE dabei helfen kann und wie ihr sie an eure Bedürfnisse anpassen könnt.

Falls ihr noch weitere Tipps hierzu habt, dann hinterlasst gerne einen Kommentar unter diesem Beitrag oder dem passenden aus der Reihe. Am nächsten Wochenende bin ich als Speaker auf dem WordCamp in Mailand. Mal sehen, was ich euch an Themen von dort mitbringen kann 🙂