Uso de PHP CodeSniffer con WordPress: Instalación y uso de las reglas de WordPress

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Si simplemente se está uniendo a la serie, hemos estado discutiendo el tema de los olores de código, cómo refactorizarlos y las herramientas que están disponibles para ayudarnos a automatizar parte de la monotonía que viene con hacerlo, especialmente en la programación de PHP.

Si no has leído los dos primeros artículos de la serie, lo recomiendo ya que cubren algunos requisitos previos que tenemos antes de seguir adelante con el resto del artículo.

Los artículos son:

En resumen, los artículos anteriores introducirán el concepto de olores de código, que hemos estado definiendo como el siguiente:

[Un] olor de código, también conocido como un mal olor, en el código de programación de equipo, se refiere a cualquier síntoma en el código fuente de un programa que posiblemente indica un problema más profundo.

Y te guiaré por los pasos necesarios para instalar PHP CodeSniffer en tu máquina.

Pero si has llegado tan lejos, supongo que eres un desarrollador de WordPress, y estás interesado en obtener PHP CodeSniffer configurado de tal manera que pueda olfatear cualquier problema en su código en lo que se refiere a los estándares de codificación de WordPress.

¡Eso es bueno! Porque en el resto de este artículo, eso es exactamente lo que vamos a cubrir.

Requisitos previos

Esta debe ser una lista muy corta. Si has seguido la serie hasta este punto, necesitas tener:

Una versión de PHP (preferiblemente 5.6.10 o posterior)
PHP CodeSniffer
Composer

Todo esto está cubierto en detalle a lo largo de los artículos anteriores de la serie, pero si has llegado tan lejos y se sienten cómodos con la línea de comandos, entonces esto debería ser una cincha en comparación con lo que hemos hecho hasta ahora.

Con todo eso dicho, vamos a empezar.

Las reglas de WordPress para PHP CodeSniffer

En primer lugar, busque las reglas de WordPress Coding Standards en GitHub. Son fáciles de encontrar.

Puede leer todos los detalles del proyecto desde la página del proyecto, pero lo más importante que quiero compartir es el siguiente:

Este proyecto es una colección de reglas PHP_CodeSniffer (sniffs) para validar el código desarrollado para WordPress. Garantiza la calidad del código y la adhesión a las convenciones de codificación, especialmente los estándares oficiales de codificación de WordPress.

Me gustaría llamar su atención sobre la frase que hace referencia a los "estándares oficiales de codificación de WordPress". Tenga en cuenta que estas reglas se basan en los estándares de codificación de WordPress. Es decir, no se puede hacer referencia oficial a ellos.

Si usted está buscando para encontrar una manera de mirar a través de las reglas que define WordPress, echa un vistazo a este artículo en el Codex. Es fácil de seguir, fácil de leer, pero mucho para recordar. Afortunadamente, tenemos el conjunto de reglas enlazado anteriormente.

Lo importante a tener en cuenta es que incluso si no está familiarizado con las reglas, el CodeSniffer encontrará los problemas con su código y le notificará de lo que necesita arreglar. Aunque usted no tiene que leer el artículo del Codex, a veces puede ayudar a identificar lo que se necesita sobre la base de los errores o advertencias que genera el sniffer.

1. Instale las reglas de WordPress

Suponiendo que ha instalado correctamente PHP CodeSniffer, vamos a agregar las reglas de WordPress al software. Para este tutorial, voy a hacer todo a través de la línea de comandos para ser lo más agnóstico posible. Voy a ofrecer unas palabras sobre IDEs y las reglas al final de la serie.

Abra su terminal y navegue hasta donde tiene su copia de PHP CodeSniffer instalado. Si has estado siguiendo esta serie de tutoriales, entonces es probable que tengamos un archivo composer.json que nos traerá esto. Si no, recuerde crear composer.json en la raíz de su proyecto y agregue esto al archivo:

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

Una vez hecho esto, ejecute composer update desde su Terminal y tendrá todo lo necesario para empezar. Para verificar la instalación, ejecute el siguiente comando:

1	$ vendor/bin/phpcs --version

Y deberías ver algo como el siguiente resultado:

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

Perfecto. A continuación, vamos a instalar las reglas de WordPress. Ya que estamos usando Composer (y continuaremos haciéndolo), esto es muy fácil de hacer.

Ejecute el comando siguiente desde el directorio raíz de su proyecto:

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

Tenga en cuenta que se le puede mostrar la siguiente pregunta:

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

Si sabes lo que estás haciendo, entonces siéntete libre de seguir adelante y seleccionar 'n'; De lo contrario, estarás bien golpeando 'y'.

2. Agregue las reglas a PHP CodeSniffer

Ahora que PHP CodeSniffer está instalado, y las reglas de WordPress están instaladas, necesitamos asegurarnos de que PHP CodeSniffer es consciente de nuestro nuevo conjunto de reglas. Para ello, necesitamos introducir el siguiente comando en la línea de comandos.

Desde la raíz del directorio del proyecto, ingrese el siguiente comando:

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

Para verificar que se han agregado las nuevas reglas, podemos pedir a PHP CodeSniffer que nos informe de los conjuntos de reglas que actualmente tiene disponibles. En el Terminal, ingrese el siguiente comando:

1	$ vendor/bin/phpcs -i

Y deberías ver la siguiente salida (o algo muy similar):

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

Observe en la línea anterior que tenemos varios conjuntos de reglas con respecto a WordPress. Bastante ordenado, ¿no? Por supuesto, veamos cómo esto se apila cuando ejecutamos los conjuntos de reglas contra un complemento como Hello Dolly.

3. Ejecutar PHP CodeSniffer contra proyectos de WordPress

Suponiendo que está trabajando en un directorio que incluye un complemento de WordPress, puede omitir el siguiente paso. Si, por otro lado, no tiene una copia de un script de WordPress, archivo, tema o complemento instalado en el directorio del proyecto, siga adelante y copie uno a su directorio de proyecto ahora.

Como se mencionó, estaremos probando el complemento Hello Dolly.

Para ejecutar PHP CodeSniffer con las reglas de WordPress contra los archivos en el directorio del complemento, ingrese el siguiente comando en el Terminal:

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

Esto resultará en una salida que debería corresponder a lo que se ve aquí:

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

Por supuesto, algunas de estas cosas pueden cambiar dependiendo de cuando estás leyendo este tutorial.

Los errores deben ser bastante claros en cuanto a lo que necesita ser arreglado:

La primera columna denota la línea en la que existe el problema.
La segunda columna determina si hay un error o una advertencia.
La tercera columna explica el problema y lo que se espera del código.

Tenga en cuenta que aunque se trata de errores o advertencias, el código, obviamente, seguirá funcionando. Pero vamos a sacar esto a través de extremo a extremo y ver lo que es como para arreglar un complemento, posiblemente el más popular ya que viene con cada instalación de WordPress, y revisar las diferencias en la calidad del código.

4. Refactorización Hello Dolly

Tenga en cuenta el complemento, antes de comenzar a trabajar en él, incluye el siguiente código fuente:

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

?>

Debe ser relativamente fácil de seguir, ya que utiliza sólo unas pocas funciones básicas de PHP y Matt ha hecho un buen trabajo de comentar el código.

Pero dado los 14 errores que encontró el CodeSniffer, vamos a refactorizar el complemento. Teniendo en cuenta los errores que presentaron y lo que está esperando ver, vamos a abordar cada uno de ellos.

Una vez hecho esto, el complemento debería ser similar al siguiente:

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

}

Observe que el complemento continúa funcionando y el código es un poco más limpio. Por último, vamos a verificar que esto pasa la prueba PHP CodeSniffer. Vamos a volver a ejecutar el código que utilizamos anteriormente para evaluar inicialmente el complemento.

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

Y la salida que vemos:

1	Skyhopper5:tutsplus_demo tommcfarlin$

Exactamente: No debe haber salida. En su lugar, debería ser un retorno al símbolo del sistema estándar.

Excelente. El complemento se ha llevado a la norma. Esta es la razón por la cual tener un sniffer de código es tan valioso: Encuentra los errores en su código basado en las reglas que usted define y luego reporta cualquier error que pueda existir.

En última instancia, esto garantiza que está liberando el código escrito de la más alta calidad en un sitio de producción. Ahora bien, esto no significa que deba evitar las pruebas unitarias u otros tipos de pruebas, ni tampoco significa que los errores no existan. Sólo significa que su código es de un alto nivel.

Conclusion

Y con eso, concluimos la serie sobre el uso de PHP CodeSniffer. Recuerde que a lo largo de la serie, hemos cubierto la idea de los olores de código, cómo refactorizarlos, y qué herramientas están disponibles para nosotros cuando se trabaja con aplicaciones PHP.

En este artículo, vimos cómo podemos usar un conjunto de reglas proporcionadas para los Estándares de Codificación de WordPress para evaluar nuestro código mientras trabajamos en un proyecto nuevo o en un proyecto existente. Tenga en cuenta que algunos IDEas admiten la posibilidad de ejecutar las reglas mientras se escribe código.

Aunque eso está más allá del alcance de este tutorial en particular, puede encontrar recursos para esto en varios lugares a través de la web. Simplemente busque su IDE por nombre, determine su compatibilidad con PHP CodeSniffer y, a continuación, asegúrese de instalar las reglas de WordPress como hemos detallado en este tutorial.

Si disfrutó este artículo o esta serie, puede estar interesado en revisar otras cosas que he escrito tanto en mi página de perfil como en mi blog. También puede seguirme en Twitter en @tommcfarlin donde a menudo hablo y comparto varias prácticas de desarrollo de software en el contexto de WordPress.

Dicho esto, no dude en dejar cualquier pregunta o comentario en el feed de abajo y voy a tratar de responder a cada uno de ellos.