PHP CodeSniffer mit WordPress verwenden: Installieren und Verwenden der WordPress-Regeln

() translation by (you can also view the original English article)

Wenn Sie gerade an der Serie teilnehmen, haben wir uns mit dem Thema Codegerüche befasst, wie Sie sie umgestalten können, und mit Tools, die uns dabei helfen, die Monotonie zu automatisieren, die damit verbunden ist, insbesondere in der PHP-Programmierung.

Wenn Sie die ersten beiden Artikel der Serie nicht gelesen haben, empfehle ich es, da sie einige Voraussetzungen für den Rest des Artikels enthalten.

Die Artikel sind:

Kurz gesagt, die obigen Artikel werden das Konzept der Codegerüche vorstellen, das wir wie folgt definiert haben:

[Ein] Codegeruch, im Computerprogrammiercode auch als schlechter Geruch bekannt, bezieht sich auf ein Symptom im Quellcode eines Programms, das möglicherweise auf ein tieferes Problem hinweist.

Ich werde Sie durch die Schritte führen, die für die Installation von PHP CodeSniffer auf Ihrem Computer erforderlich sind.

Aber wenn Sie es soweit geschafft haben, nehme ich an, Sie sind ein WordPress-Entwickler, und Sie möchten PHP CodeSniffer so konfigurieren, dass es Probleme in Ihrem Code erkennt, die sich auf die WordPress-Codierstandards beziehen.

Das ist gut! Im Rest dieses Artikels werden wir genau das behandeln.

Voraussetzungen

Dies sollte eine sehr kurze Liste sein. Wenn Sie die Serie bis zu diesem Punkt verfolgt haben, müssen Sie Folgendes haben:

eine Version von PHP (vorzugsweise 5.6.10 oder höher)
PHP CodeSniffer
Komponist

All das wird in den vorherigen Artikeln der Serie ausführlich behandelt. Wenn Sie jedoch so weit gekommen sind und mit der Befehlszeile vertraut sind, sollte dies im Vergleich zu dem, was wir bisher gemacht haben, ein Kinderspiel sein.

Nachdem alles gesagt ist, lass uns anfangen.

Die WordPress-Regeln für PHP CodeSniffer

Suchen Sie zunächst die Regeln für WordPress-Codierungsstandards auf GitHub. Sie sind leicht zu finden.

Sie können alles über die Details des Projekts auf der Projektseite nachlesen. Das Wichtigste, das ich Ihnen mitteilen möchte, ist Folgendes:

Dieses Projekt ist eine Sammlung von PHP_CodeSniffer-Regeln (Schnüffeln), um für WordPress entwickelten Code zu überprüfen. Es gewährleistet die Codequalität und die Einhaltung der Codierungskonventionen, insbesondere der offiziellen WordPress-Codierungsstandards.

Ich möchte Ihre Aufmerksamkeit auf den Satz lenken, der auf die "offiziellen WordPress-Codierstandards" verweist. Beachten Sie, dass diese Regeln auf den WordPress-Codierungsstandards basieren. Sie können sie also nicht offiziell referenzieren.

Wenn Sie nach den Regeln suchen, die WordPress definiert, lesen Sie diesen Artikel im Codex. Es ist leicht zu folgen, leicht zu lesen, aber es ist viel zu merken. Zum Glück haben wir die oben verlinkte Regel.

Wichtig ist, dass der CodeSniffer die Probleme mit Ihrem Code findet und Sie darüber informiert, was Sie beheben müssen, auch wenn Sie mit den Regeln nicht vertraut sind. Obwohl Sie den Codex-Artikel nicht lesen müssen, kann er manchmal helfen, anhand der Fehler oder Warnungen, die der Sniffer generiert, herauszufinden, was erforderlich ist.

1. Installieren Sie die WordPress-Regeln

Vorausgesetzt, Sie haben PHP CodeSniffer ordnungsgemäß installiert, fügen wir der Software die WordPress-Regeln hinzu. Für dieses Tutorial mache ich alles über die Befehlszeile, um möglichst plattformunabhängig zu sein. Ich werde am Ende der Serie ein paar Worte zu IDEs und Regeln geben.

Öffnen Sie Ihr Terminal und navigieren Sie zu der Stelle, an der Sie PHP CodeSniffer installiert haben. Wenn Sie diese Serie von Tutorials mitverfolgt haben, erinnern Sie sich wahrscheinlich daran, dass wir eine composer.json-Datei haben, die dies für uns in den Griff bekommt. Wenn nicht, denken Sie daran, composer.json im Stammverzeichnis Ihres Projekts zu erstellen und fügen Sie der Datei Folgendes hinzu:

{
    "require": {
        "squizlabs/php_codesniffer": "2.*"
    }
}

Wenn Sie fertig sind, führen Sie $ composer update von Ihrem Terminal aus aus, und Sie haben alles, was Sie brauchen, um loszulegen. Führen Sie den folgenden Befehl aus, um die Installation zu überprüfen:

1	$ vendor/bin/phpcs --version

Und Sie sollten ungefähr die folgende Ausgabe sehen:

1	PHP_CodeSniffer version 2.6.0 (stable) by Squiz (https://www.squiz.net)

Perfekt. Als nächstes installieren wir die WordPress-Regeln. Da wir Composer verwenden (und dies auch weiterhin tun werden), ist dies sehr einfach.

Führen Sie den folgenden Befehl aus dem Stammverzeichnis Ihres Projekts aus:

1	composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Beachten Sie, dass Sie möglicherweise mit der folgenden Frage aufgefordert werden:

1	Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?

Wenn Sie wissen, was Sie tun, können Sie "n" auswählen. Andernfalls können Sie 'y' gut treffen.

2. Fügen Sie die Regeln zu PHP CodeSniffer hinzu

Nun, da PHP CodeSniffer installiert ist und die WordPress-Regeln installiert sind, müssen wir sicherstellen, dass PHP CodeSniffer unseren neuen Regelsatz kennt. Dazu müssen wir den folgenden Befehl in die Befehlszeile eingeben.

Geben Sie im Stammverzeichnis Ihres Projektverzeichnisses den folgenden Befehl ein:

1	$ vendor/bin/phpcs --config-set installed_paths wpcs

Um zu überprüfen, ob die neuen Regeln hinzugefügt wurden, können wir PHP CodeSniffer bitten, uns die Regelsätze mitzuteilen, die derzeit verfügbar sind. Geben Sie im Terminal den folgenden Befehl ein:

1	$ vendor/bin/phpcs -i

Und Sie sollten die folgende Ausgabe sehen (oder etwas sehr Ähnliches):

1	The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra and WordPress-VIP

Beachten Sie in der obigen Zeile, dass wir einige Regeln bezüglich WordPress haben. Ziemlich ordentlich, nicht wahr? Mal sehen, wie sich das stapelt, wenn wir die Regelsätze gegen ein Plugin wie Hello Dolly ausführen.

3. Ausführen von PHP CodeSniffer gegen WordPress-Projekte

Angenommen, Sie arbeiten an einem Verzeichnis, das ein WordPress-Plugin enthält, können den folgenden Schritt überspringen. Wenn Sie andererseits keine Kopie eines WordPress-Skripts, einer Datei, eines Designs oder eines Plugins im Projektverzeichnis installiert haben, kopieren Sie sie jetzt in Ihr Projektverzeichnis.

Wie bereits erwähnt, werden wir das Hello Dolly-Plugin testen.

Um PHP CodeSniffer mit den WordPress-Regeln für die Dateien im Plugin-Verzeichnis auszuführen, geben Sie im Terminal den folgenden Befehl ein:

1	$ vendor/bin/phpcs --standard=WordPress hello-dolly

Dies führt zu einer Ausgabe, die dem entsprechen sollte, was Sie hier sehen:

FILE: /Users/tommcfarlin/Desktop/tutsplus_demo/hello-dolly/hello.php
----------------------------------------------------------------------
FOUND 14 ERRORS AFFECTING 14 LINES
----------------------------------------------------------------------
  2 | ERROR | Missing short description in doc comment
  5 | ERROR | There must be exactly one blank line after the file
    |       | comment
  6 | ERROR | Empty line required before block comment
 15 | ERROR | You must use "/**" style comments for a function
    |       | comment
 46 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 49 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 53 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 54 | ERROR | You must use "/**" style comments for a function
    |       | comment
 56 | ERROR | Expected next thing to be an escaping function (see
    |       | Codex for 'Data Validation'), not '"<p
    |       | id='dolly'>$chosen</p>"'
 59 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 62 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 63 | ERROR | You must use "/**" style comments for a function
    |       | comment
 64 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 67 | ERROR | Expected next thing to be an escaping function (see
    |       | Codex for 'Data Validation'), not '"
    |       | '
----------------------------------------------------------------------

Natürlich können sich einige dieser Dinge ändern, wenn Sie dieses Tutorial lesen.

Die Fehler sollten ziemlich klar sein, was behoben werden muss:

Die erste Spalte gibt die Zeile an, in der das Problem besteht.
Die zweite Spalte bestimmt, ob ein Fehler oder eine Warnung vorliegt.
Die dritte Spalte erläutert das Problem und die Erwartungen an den Code.

Obwohl dies Fehler oder Warnungen sind, funktioniert der Code natürlich weiterhin. Aber lassen Sie uns das alles durchgehen und sehen, wie es ist, ein Plugin zu reparieren, das wohl das beliebteste ist, da es mit jeder WordPress-Installation kommt, und die Unterschiede in der Qualität des Codes überprüfen.

4. Refactoring Hallo Dolly

Beachten Sie, dass das Plugin den folgenden Quellcode enthält, bevor wir mit der Arbeit beginnen:

<?php
/**
 * @package Hello_Dolly
 * @version 1.6
 */
/*
Plugin Name: Hello Dolly
Plugin URI: https://wordpress.org/plugins/hello-dolly/
Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.
Author: Matt Mullenweg
Version: 1.6
Author URI: http://ma.tt/
*/

function hello_dolly_get_lyric() {
    /** These are the lyrics to Hello Dolly */
  $lyrics = "Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
So, take her wrap, fellas
Find her an empty lap, fellas
Dolly'll never go away again
Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
Golly, gee, fellas
Find her a vacant knee, fellas
Dolly'll never go away
Dolly'll never go away
Dolly'll never go away again";

	// Here we split it into lines
	$lyrics = explode( "\n", $lyrics );

	// And then randomly choose a line
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}

// This just echoes the chosen line, we'll position it later
function hello_dolly() {
	$chosen = hello_dolly_get_lyric();
	echo "<p id='dolly'>$chosen</p>";
}

// Now we set that function up to execute when the admin_notices action is called
add_action( 'admin_notices', 'hello_dolly' );

// We need some CSS to position the paragraph
function dolly_css() {
	// This makes sure that the positioning is also good for right-to-left languages
	$x = is_rtl() ? 'left' : 'right';

	echo "
	<style type='text/css'>
	#dolly {
		float: $x;
		padding-$x: 15px;
		padding-top: 5px;		
		margin: 0;
		font-size: 11px;
	}
	</style>
	";
}

add_action( 'admin_head', 'dolly_css' );

?>

Es sollte relativ einfach zu folgen sein, da es nur ein paar grundlegende PHP-Funktionen verwendet und Matt den Code gut kommentiert.

Aber angesichts der 14 Fehler, die der CodeSniffer gefunden hat, wollen wir das Plugin umgestalten. Unter Berücksichtigung der Fehler und der erwarteten Fehler sollten wir uns an jeden wenden.

Sobald das Plugin fertig ist, sollte es folgendermaßen aussehen:

<?php
/**
 * This is a plugin that symbolizes the hope and enthusiasm of an entire
 * generation summed up in two words sung most famously by Louis Armstrong.
 *
 * @package Hello_Dolly
 * @version 1.6
 *
 * @wordpress-plugin
 * Plugin Name: Hello Dolly
 * Plugin URI: https://wordpress.org/plugins/hello-dolly/
 * Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.
 * Author: Matt Mullenweg
 * Version: 1.6
 * Author URI: http://ma.tt/
 */

/**
 * Defines the lyrics for 'Hello Dolly'.
 *
 * @return string A random line of from the lyrics to the song.
 */
function hello_dolly_get_lyric() {
    /** These are the lyrics to Hello Dolly */
    $lyrics = "Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
So, take her wrap, fellas
Find her an empty lap, fellas
Dolly'll never go away again
Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
Golly, gee, fellas
Find her a vacant knee, fellas
Dolly'll never go away
Dolly'll never go away
Dolly'll never go away again";

	// Here we split it into lines.
	$lyrics = explode( "\n", $lyrics );

	// And then randomly choose a line.
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}

add_action( 'admin_notices', 'hello_dolly' );
/**
 * This just echoes the chosen line, we'll position it later. This function is
 * set up to execute when the admin_notices action is called.
 */
function hello_dolly() {

	$chosen = hello_dolly_get_lyric();
	echo "<p id='dolly'>$chosen</p>"; // WPCS: XSS OK.

}

add_action( 'admin_head', 'dolly_css' );
/**
 * Add some CSS to position the paragraph.
 */
function dolly_css() {

	/**
	 *This makes sure that the positioning is also good for right-to-left languages.
	 */
	$x = is_rtl() ? 'left' : 'right';
	echo "<style type='text/css'> #dolly { float: $x; padding-$x: 15px; padding-top: 5px; margin: 0; font-size: 11px; } </style> "; // WPCS: XSS OK.

}

Beachten Sie, dass das Plugin weiterhin funktioniert und der Code etwas sauberer ist. Als letztes überprüfen wir, ob der PHP CodeSniffer-Test erfolgreich ist. Lassen Sie uns den Code, den wir oben verwendet haben, erneut ausführen, um das Plugin zunächst auszuwerten.

1	$ vendor/bin/phpcs --standard=WordPress hello-dolly

Und die Ausgabe, die wir sehen:

1	Skyhopper5:tutsplus_demo tommcfarlin$

Genau: Es sollte keine Ausgabe geben. Stattdessen sollte es eine Rückkehr zur Standardbefehlsaufforderung sein.

Ausgezeichnet. Das Plugin wurde auf den Standard gebracht. Aus diesem Grund ist ein Code-Sniffer so wertvoll: Er findet die Fehler in Ihrem Code anhand der von Ihnen definierten Regeln und meldet dann alle möglicherweise vorhandenen Fehler.

Dies stellt letztendlich sicher, dass Sie Code mit der höchsten Qualität in eine Produktionsumgebung einbinden. Das bedeutet nicht, dass Sie Unit-Tests oder andere Arten von Tests vermeiden sollten. Dies bedeutet auch, dass keine Fehler vorhanden sind. Es bedeutet nur, dass Ihr Code einem hohen Standard entspricht.

Fazit

Damit schließen wir die Reihe zur Verwendung von PHP CodeSniffer ab. Erinnern wir uns daran, dass wir uns in der gesamten Serie mit der Idee von Codegerüchen befasst haben, wie man sie umgestalten kann und welche Tools bei der Arbeit mit PHP-Anwendungen zur Verfügung stehen.

In diesem Artikel haben wir gesehen, wie wir einen Satz von Regeln für die WordPress-Codierungsstandards verwenden können, um unseren Code während der Arbeit an einem neuen oder vorhandenen Projekt zu bewerten. Beachten Sie, dass einige IDEs die Möglichkeit unterstützen, die Regeln beim Schreiben von Code auszuführen.

Obwohl dies den Rahmen dieses speziellen Tutorials sprengt, können Sie an verschiedenen Stellen im Web Ressourcen dafür finden. Suchen Sie einfach nach Ihrer IDE anhand des Namens, ermitteln Sie deren Unterstützung für PHP CodeSniffer, und installieren Sie anschließend die in diesem Tutorial beschriebenen WordPress-Regeln.

Wenn Ihnen dieser Artikel oder diese Serie gefallen hat, interessieren Sie sich vielleicht auch für andere Dinge, die ich auf meiner Profilseite oder in meinem Blog geschrieben habe. Sie können mir auch auf Twitter unter @tommcfarlin folgen, wo ich oft über Softwareentwicklungspraktiken im Rahmen von WordPress spreche und diese teile.

Zögern Sie nicht, Fragen oder Kommentare im Feed unten zu hinterlassen, und ich werde versuchen, auf jeden einzelnen von ihnen zu antworten.