Usare PHP CodeSniffer con WordPress: Installazione e uso delle regole di WordPress

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

Se voi state completando la serie di articoli, in cui abbiamo discusso l'argomento del code smells, come fare il loro refactor, e degli strumenti che sono disponibili per aiutarci ad automatizzare alcune ricorsive che ci vengono in aiuto, soprattutto con la programmazione in PHP.

Se non avete letto i primi due articoli di questa serie, lo consiglio in quanto coprono alcuni prerequisiti necessari prima di andare avanti con il resto di questo articolo

Gli articoli sono:

In breve, gli articoli sopra introducono il concetto del code smell, che andiamo definendo come segue:

[A] code smell, anche conosciuto come bad smell, nel codice di programmazione informatica, si riferisce a qualsiasi sintomo nel codice sorgente di un programma che potrebbe indicare un problema più profondo.

Vi guiderò attraverso i passi necessari per installare PHP CodeSniffer nelle vostre macchine.

Se siete arrivati sino a questo punto, si presume che siate sviluppatori WordPress, e che siate interessati a configurare PHP CodeSniffer in modo tale da poter fiutare eventuali problemi nel codice in relazione alla WordPress Coding Standards.

Bene! Perchè nel resto del capitolo andremo a scoprire proprio questo.

Prerequisiti

Questa dovrebbe essere una lista molto breve. Se avete seguito la serie di articoli fino a questo punto, voi dovreste avere:

una versione di PHP ( preferibilmente 5.6.10 o sucessiva)
PHP CodeSniffer
Composer

Tutto questo è spiegato in dettaglio nel corso dei precedenti articoli della serie, ma se siete arrivati fino a questo punto e avete dimestichezza con la linea di comando , allora questo dovrebbe essere un gioco da ragazzi in confronto a quello che abbiamo fatto finora .

Detto tutto ciò, cominciamo.

Le regole di WordPress per PHP CodeSniffer

Primo , individuare il WordPress Coding Standards rules su GitHub . Sono facili da trovare

Potete leggere tutti i dettagli del progetto dalla pagina del progetto, ma la cosa più importante che vorrei condividere è la seguente :

Questo progetto è una collezione di regole PHP_CodeSniffer (sniff) per convalidare il codice sviluppato per WordPress Questo assicura la qualità del codice e l'aderenza alle convenzioni di codifica, specialmente con l'ufficiale WordPress Coding Standards

Mi piacerebbe portare la vostra attenzione alla frase che fa riferimento al " ufficiale WordPress Coding Standards ". Si noti che queste regole si basano sui WordPress Coding Standards. Ciò significa, che non potete non riferivi ad esse.

Se state cercando un modo per vedere la definizione delle regole di WordPress, controllate questo articolo del Codex Sono semplici da seguire, facili da leggere, ma c'è molto da memorizzare. Per fortuna, abbiamo il set di regole nel link sopra.

La cosa importante da notare è che se non avete familiarità con le regole, il CodeSniffer troverà il problema nel vostro codice e vi notificherà cosa dovrete risolvere. Anche se non c'è bisogno di leggere l'articolo sul Codex, a volte può aiutare a identificare ciò che è necessario in base ai errori o avvisi generati dallo sniffer.

Installare WordPress Rules

Supponendo di aver correttamente installato PHP CodeSniffer, aggiungiamo le regole di WordPress per il software. Per questo tutorial, andrò a fare ogni cosa via linea di comando così da essere il più indipendente possibile dalla piattaforma. Offrirò qualche parola riguardo IDEs e regole alla fine delle serie.

Aprite il vostro Terminal e navigate dove avete installato la vostra copia di CodeSniffer. Se avete seguito fin qui questa serie di tutorials, è probabile che voi abbiate un richiamo al file composer.json che farà questo per noi. Se così non è, ricordate di creare composer.json nella root del vostro progetto e di aggiungere nel file:

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

Una volta fatto, avviate $ composer update dal vostro Terminale avrete tutto quello che serve per andare avanti. Per verificare l'installazione, avviate il seguente comando:

1	$ vendor/bin/phpcs --version

Dovreste vedere qualcosa di simile al seguente output:

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

Perfetto. Successivamente, andiamo ad installare le regole di WordPress. Dal momento che stiamo usando Composer (e continueremo a farlo), questo è molto facile da fare.

Avviate il seguente comando all'interno della directory principale del vostro progetto:

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

Si noti che è possibile che venga mostrata la seguente domanda:

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

Se sapete cosa state facendo, sentitevi liberi di andare avanti e selezionate 'n'; altrimenti andrà bene battere 'y'.

2. Aggiungere le regole per PHP CodeSniffer

Ora che PHP CodeSniffer è installato, e le regole di WordPress sono installate, abbiamo bisogno di fare in modo che PHP Code Sniffer sia a conoscenza del nostro nuovo set di regole. Per fare questo, dobbiamo battere il seguente comando nella riga di comando.

Nella root della directory del vostro progetto, inserite il seguente comando:

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

Per verificare che le nuove regole siano state aggiunte, possiamo chiedere a PHP CodeSniffer di mostrarci i set di regole che attualmente ha disponibili. Nel terminal, inserire il seguente comando:

1	$ vendor/bin/phpcs -i

Si dovrebbe vedere il seguente output (o qualcosa di molto simile):

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

Si noti nella riga sopra che abbiamo diverse serie di regole riguadanti WordPress. Piuttosto pulito, non è vero? Naturalmente, vediamo come questo aumenta quando si esegue il set di regole verso un plugin come Hello Dolly.

3. Avviare PHP CodeSniffer verso WordPress Projects

Supponendo che si stia lavorando su una directory che include un plugin per WordPress, allora si può saltare il passo successivo. Se, d'altra parte, non avete una copia di uno script di WordPress, file, tema o plugin installato nella directory del progetto, andare avanti e copiare uno sopra alla directory del progetto in questo momento.

Come già detto, andremo a testare il plugin Hello Dolly.

Per eseguire PHP CodeSniffer con le regole di WordPress verso i file nella directory dei plugin, immettere il seguente comando nel terminale:

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

Questo si tradurrà in output che deve corrispondere a quello che vedete qui:

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 '"
    |       | '
----------------------------------------------------------------------

Naturalmente, alcune di queste cose potrà essere diversa a seconda di quando starete leggendo questo tutorial.

Gli errori dovrebbero essere abbastanza chiari per quanto riguarda ciò che deve essere risolto:

La prima colonna indica la riga in cui esiste il problema.
La seconda colonna determina se c'è un errore o un avviso.
La terza colonna spiega il problema e che cosa è previsto dal codice.

Si noti che anche se si tratta di errori o avvisi, il codice ovviamente funzionerà ancora. Ma vediamo attraverso l'end-to-end cosa vuol dire sistemare un plugin, senza dubbio il più popolare, dato che si trova con ogni installazione di WordPress, ed esaminiamo le differenze nella qualità del codice.

4. Refactoring Hello Dolly

Notate il plugin, prima di cominciare lavoro su esso, include il codice sorgente riportato di seguito:

<?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' );

?>

Dovrebbe essere relativamente facile da seguire in quanto si usano solo poche caratteristiche di PHP id base e Matt ha fatto un buon lavoro di commento del codice.

Ma dato i 14 errori che il CodeSniffer ha trovato, andiamo a fare il refactoring del plugin. Prendendo in considerazione gli errori che si sono presentati e che cosa ci si aspetta di vedere, andiamo affrontare ciascuno di essi.

Una volta fatto, il plugin dovrebbe essere simile al seguente:

<?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.

}

Si noti che il plugin continua a lavorare e il codice è un po' più pulito. Infine, andiamo a verificare che passi il test di CodeSniffer di PHP. Andiamo ad eseguire nuovamente il codice che abbiamo usato in precedenza per valutare inizialmente il plugin.

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

E l'output che vediamo:

1	Skyhopper5:tutsplus_demo tommcfarlin$

Esattamente: non ci dovrebbe essere alcun output. Invece, dovrebbe essere un ritorno al prompt dei comandi standard.

Eccellente. Il plugin è stato portato allo standard. Ecco perché avere uno code sniffer è così prezioso: trova gli errori nel codice in base alle regole definite e quindi segnala gli eventuali errori che possono esistere.

In definitiva, questo assicura che voi rilascerete la massima qualità di codice scritta in un sito a livello di produzione. Ora, questo non significa che si potrebbe evitare unit testing o altri tipi di test, né significa che i bug non esistano. Significa solo che il vostro codice è ad un alto livello.

Conclusione

E con questo, concludiamo la serie sull'utilizzo di PHP CodeSniffer. Ricordo che durante la serie, abbiamo trattato l'argomento del code smell, come effettuare il refactoring di essi, e quali strumenti sono disponibili quando si lavora con applicazioni PHP.

In questo articolo, abbiamo visto come possiamo usare un set di regole per gli standard di codifica di WordPress fornito per valutare il nostro codice mentre si lavora su un progetto nuovo o esistente. Si noti che alcuni IDEs supportano la possibilità di eseguire le regole durante la scrittura di codice.

Anche se ciò è oltre lo scopo di questo tutorial, potrete trovare le risorse per questo in tutto il web. Cerca semplicemente il vostro IDE per nome, determinate il suo supporto per PHP CodeSniffer e quindi assicurarsi di installare le regole di WordPress come noi abbiamo descritto in dettaglio in questo tutorial.

Se vi è piaciuto questo articolo o questa serie di articoli, potreste essere interessati a verificare altre cose che ho scritto sia sulla mia pagina di profilo che sul mio blog. Potete anche seguirmi su Twitter @tommcfarlin dove spesso si parla e condividono le varie procedure di sviluppo software all'interno di WordPress.

Detto questo, non esitate a lasciare qualsiasi domanda o commento nel feed sotto ed io risponderò a ciascuno di essi.