Usando PHP CodeSniffer con WordPress: Instalando y usando PHP CodeSniffer

Spanish (Español) translation by Marilu (you can also view the original English article)

En el primer artículo de esta serie, definimos los olores del código y vimos algunos ejemplos de lo que son y cómo podemos refactorizarlos para mejorar la calidad del código. Recordemos:

[A] código oloroso, también conocido como mal olor, en el código de programación de las computadoras, se refiere a cualquier síntoma en el código fuente de un programa que posiblemente indica un problema más profundo.

Últimamente, estamos trabajando en la implementación de reglas específicas de WordPress, pero antes de hacerlo es importante familiarizarse con PHP CodeSniffer.

En este artículo, vamos a echar un vistazo a lo que es PHP CodeSniffer, cómo instalarlo, cómo ejecutarlo contra un script de ejemplo, y cómo refactorizar dicho script. Luego veremos cómo vamos a avanzar en el código específico de WordPress.

Si tienes un entorno de desarrollo local establecido, entonces genial; si no, está bien. Te proporcionaré algunos enlaces que te pondrán en marcha rápidamente.

Dicho esto, empecemos.

Requisitos previos

Antes de empezar, es importante que tengas algún tipo de entorno de desarrollo local, aunque solo incluya una copia del intérprete de PHP.

Puede que ya tengas una copia

Nota que si estás ejecutando una variante de Linux o OS X, hay una posibilidad de que ya tengas PHP instalado. Si lo haces, entonces no tienes que preocuparte por nada más en esta sección. Para determinar si tienes PHP instalado, ejecuta el siguiente comando en la línea de comandos:

$ php -v

Deberías ver algo como lo siguiente (aunque tu salida puede ser diferente según la versión de PHP que hayas optado por ejecutar):

1	PHP 5.6.10 (cli) (built: Jul 6 2015 14:28:54)
2	Copyright (c) 1997-2015 The PHP Group
3	Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

Si eres más avanzado y tienes varias copias del proyecto instaladas, entonces puedes correr:

1	$ which php

Y deberías ver algo como esto:

1	/Applications/MAMP/bin/php/php5.6.10/bin/php

Aunque tu salida variará dependiendo de dónde esté instalada tu copia de PHP.

Pero si no lo haces, ¡está bien!

Aunque esta serie está dirigida principalmente a principiantes, puede que te sientas cómodo descargando una copia de PHP e instalándolo en tu sistema. Si este eres tú, entonces toma una copia de PHP de la página principal del proyecto, instálalo, y vuelve a este tutorial.

Si, por otra parte, esto es nuevo para ti, entonces puedes elegir usar uno de los instaladores para tu sistema operativo en la página principal de PHP enlazada arriba o una de las utilidades proporcionadas abajo.

WAMP para Windows
XAMPP para Linux, Windows, u OS X
MAMP para Windows y OS X

Todos estos paquetes tienen sus propios instaladores e instalarán PHP, MySQL y Apache. Como mencioné anteriormente, nos preocupa principalmente tener una copia de PHP disponible en nuestro sistema.

Una vez instalados, intenta ejecutar los comandos mencionados en la primera parte de esta sección (o el equivalente de tu sistema) y deberías ver una salida similar.

Si no lo haces, entonces es probable que necesites añadir la ruta a PHP a tus variables de entorno. Esto está fuera del alcance de este tutorial, así que por favor consulta la documentación de la versión del proyecto que has instalado.

Con PHP ya instalado, estamos listos para empezar a atrapar y limpiar nuestro código oloroso.

¿Qué es PHP CodeSniffer?

Puedes encontrar el software oficial de PHP CodeSniffer en GitHub.

De la documentación del proyecto:

PHP_CodeSniffer es un conjunto de dos scripts PHP; el principal phpcs script que registra archivos PHP, JavaScript y CSS para detectar violaciones de un estándar de codificación definido, y un segundo script phpcbf para corregir automáticamente las violaciones del estándar de codificación. PHP_CodeSniffer es una herramienta de desarrollo esencial que asegura que tu código permanezca limpio y consistente.

Si nunca has visto nada como esto antes, suena muy bien, ¿no? Quiero decir, ¡es una herramienta que está pensada para ayudar a asegurar un cierto nivel de calidad en tu código!

Aunque el proyecto menciona lenguajes como CSS y JavaScript, nos centramos en PHP en esta serie. Esto no significa que no sea importante comprobar la calidad de esos archivos de lenguaje en particular en tus proyectos, sin embargo.

Por muy bien que suene, aún así plantea las preguntas: ¿Cómo instalamos el software, y cómo empezamos a comprobar nuestro código?

Respondamos a ambas preguntas ahora.

1. Instalación del software

Si realizas una búsqueda en Google sobre cómo instalar PHP CodeSniffer, es probable que termines con una variedad de resultados, muchos de los cuales incluirán el uso de algo llamado Pear.

Pear fue una vez el sistema de distribución de paquetes de facto para las bibliotecas de PHP, y aunque muchos paquetes todavía están disponibles a través del software, también está siendo retirado de otros paquetes populares (como PHPUnit).

Por esta razón, a menudo recomiendo usar otros métodos de instalación cuando están disponibles. Esto incluye el uso de herramientas como Composer, que es posiblemente el software de administración de dependencias más popular para PHP.

Si nunca has usado Composer antes, no te preocupes. Te daré todos los pasos que necesitas para poner PHP CodeSniffer en funcionamiento en tu máquina con Composer y con un mínimo de trabajo. Si estás interesado en aprender más, tenemos bastantes tutoriales sobre cómo usar Composer, así que no dudes en echarle un vistazo.

Instalando Composer

Antes de instalar PHP CodeSniffer, necesitamos instalar realmente Composer. Afortunadamente, es muy fácil hacerlo una vez que tienes PHP instalado y funcionando en tu máquina local.

Para instalar Composer, puedes descargar este archivo y luego ejecutar el siguiente comando en la línea de comandos desde el lugar donde descargaste el instalador de Composer:

1	$ php composer-setup.php --install-dir=bin --filename=composer

Una nota de las instrucciones de instalación de Composer:

Puedes instalar Composer en un directorio específico usando la opción --install-dir y adicionalmente (re)nombrarlo también usando la opción --filename.

Para más información, puedes consultar las instrucciones de descarga o ver el proyecto completo en GitHub.

Una vez instalado, ahora puedes usar Composer para instalar dependencias de terceros, como PHP CodeSniffer, en tus proyectos. Sin embargo, toma nota de dónde has instalado tu copia de Composer. Necesitarás referirte a él cuando lo ejecutes ya que lo ejecutaremos desde la línea de comandos.

De todos modos, vamos a crear un directorio desde el que vamos a ejecutar nuestros scripts PHP. Aunque no tendremos nada en este directorio todavía, necesitamos crear un archivo llamado composer.json.

Voy a llamar a mi directorio tutsplus-demo, e incluiré mi archivo Composer en ese directorio para empezar.

Una vez que hayas creado el archivo, coloca el siguiente código en el archivo JSON:

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

En resumen, esto le dice a Composer que instale PHP CodeSniffer cuando ejecute el comando apropiado. Nota que la directiva require hace lo siguiente:

Enumera los paquetes requeridos por este paquete. El paquete no se instalará a menos que se puedan cumplir esos requisitos.

Puede leer más sobre el esquema Composer en la documentación.

Una vez que Composer esté instalado y una vez que tengas tu archivo composer.json con el código de arriba, es hora de instalar realmente PHP CodeSniffer. Desde la línea de comandos, emitir el siguiente comando:

1	$ composer update

Ten en cuenta que esto se basa en la idea de que Composer está disponible públicamente en tu sistema. Si no, puedes ejecutarlo escribiendo la ruta completa del archivo instalado o puedes añadirlo a tus variables de entorno y luego reiniciar la sesión de terminal para recargar las variables.

Una vez que Composer haya terminado de trabajar, deberías ver algo como esto:

PHP CodeSniffer installed successfully via Composer

Y tu directorio tutsplus-code debería verse ahora así:

tutsplus-demo with the new vendor directory containing PHP CodeSniffer

Nota específicamente que tienes un directorio de proveedores. Esto significa que Composer instaló correctamente PHP CodeSniffer. En este punto, estamos listos para evaluar nuestro código PHP.

2. Evaluando los scripts

Primero, tomemos un script de muestra. El que vamos a ver se encuentra en esta respuesta en Stack Overflow.

Crea un archivo en tu directorio tutsplus-demo y llámalo sample.php. Luego, asegúrate de que el archivo contenga el siguiente contenido:

<?php
$target_dir = "uploads/";
$target_file = $target_dir . basename($_FILES["fileToUpload"]["name"]);
$uploadOk = 1;
$imageFileType = pathinfo($target_file,PATHINFO_EXTENSION);
// Check if image file is a actual image or fake image
if(isset($_POST["submit"])) {
    $check = getimagesize($_FILES["fileToUpload"]["tmp_name"]);
    if($check !== false) {
        echo "File is an image - " . $check["mime"] . ".";
        $uploadOk = 1;
    } else {
        echo "File is not an image.";
        $uploadOk = 0;
    }
}
?>

Guarda tu trabajo. A continuación, podemos ejecutar PHP CodeSniffer desde la línea de comandos y hacer que evalúe el código en el script anterior usando el conjunto de reglas estándar.

Desde tu terminal, introduce el siguiente comando:

1	$ vendor/bin/phpcs sample.php

Esto debería generar una salida que contenga lo siguiente

1	Skyhopper5:tutsplus-demo tommcfarlin$ vendor/bin/phpcs sample.php
2
3	FILE: /Users/tommcfarlin/Desktop/tutsplus-demo/sample.php
4	----------------------------------------------------------------------
5	FOUND 4 ERRORS AFFECTING 4 LINES
6	----------------------------------------------------------------------
7	2 \| ERROR \| [ ] Missing file doc comment
8	5 \| ERROR \| [x] No space found after comma in function call
9	7 \| ERROR \| [ ] Expected "if (...) {\n"; found "if(...) {\n"
10	9 \| ERROR \| [ ] Expected "if (...) {\n"; found "if(...) {\n"
11	----------------------------------------------------------------------
12	PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
13	----------------------------------------------------------------------
14
15	Time: 46ms; Memory: 3.5Mb
16
17	Skyhopper5:tutsplus-demo tommcfarlin$

Fíjate que encontró cuatro errores. La primera columna te dice en qué línea está el error, la segunda columna dice que es un error (frente a una advertencia), y el resto te dice lo que esperaba ver frente a lo que realmente vio.

Así que vamos a limpiar el archivo basado en esos errores. En términos generales, necesitamos hacer lo siguiente:

Añade un comentario de documentación a nivel de archivo.
Añade un espacio después de una coma en una llamada a un archivo de función en línea.
Añade espacios después de las declaraciones if en el script.

El resultado final sería algo como esto:

<?php
/**
 * Determines if the file being uploaded is a legitimate image or not.
 * If so, allows the file to be uploaded. Otherwise, prevents the upload
 * from occurring.
 *
 * PHP Version 5
 *
 * @category Demo
 * @package  TutsPlus_Demo
 * @author   Tom McFarlin <tom@tommcfarlin.com>
 * @license  http://opensource.org/licenses/gpl-license.php GNU Public License
 * @link     http://is.gd/dq0DhO
 * @since    1.0.0
 */

$target_dir = "uploads/";
$target_file = $target_dir . basename($_FILES["fileToUpload"]["name"]);
$uploadOk = 1;
$imageFileType = pathinfo($target_file, PATHINFO_EXTENSION);
// Check if image file is a actual image or fake image
if (isset($_POST["submit"])) {
    $check = getimagesize($_FILES["fileToUpload"]["tmp_name"]);
    if ($check !== false) {
        echo "File is an image - " . $check["mime"] . ".";
        $uploadOk = 1;
    } else {
        echo "File is not an image.";
        $uploadOk = 0;
    }
}
?>

A continuación, ejecuta el script de nuevo y no deberías obtener ningún resultado. Es decir, se te debería presentar el símbolo del sistema estándar. A veces esto significa que algo está roto, pero en este caso significa que todo está funcionando como se esperaba

No está mal, ¿verdad?

Ahora imagina lo que esto podría hacer para las bases de código más grandes y los scripts con los que trabajas a diario.

No es una muleta

Por importante que sea evaluar nuestro código, evitar los olores del código y aspirar a la mayor calidad posible, herramientas como PHP CodeSniffer no están pensadas para ser usadas como muletas. Eso significa que no tenemos una excusa para escribir código malo porque otra herramienta lo atrapará.

Porque no siempre lo hará.

En su lugar, esto es una especie de segunda pasada. Es decir, está destinado a captar cosas que podemos pasar por alto al escribir el código la primera, segunda o novena vez. Lo bueno de este programa en particular es que puedes cargar diferentes reglas en PHP CodeSniffer dependiendo del entorno, marco de trabajo o biblioteca con la que estés trabajando.

Y eso es exactamente lo que vamos a hacer con WordPress en el próximo artículo.

Conclusión

En lo que respecta al material de introducción, hemos cubierto bastante terreno en este tutorial. Es decir, hemos mirado la creación de un entorno de desarrollo básico en nuestra máquina local que incluye PHP.

A continuación, hemos echado un vistazo a Composer y cómo instalarlo en nuestro sistema. Hemos escrito nuestro primer archivo de Composer para recuperar las dependencias, a saber, PHP CodeSniffer, e incluso hemos evaluado y corregido los resultados que nos proporcionó el software.

Si eres principalmente un desarrollador de PHP, espero que los dos primeros artículos de la serie hayan sido útiles, pero si eres un desarrollador de WordPress entonces tenemos un poco más que cubrir.

En el último artículo de la serie, vamos a centrarnos en WordPress. Debido a que tiene su propio conjunto de normas de codificación, vamos a ver cómo cargar estas reglas en PHP CodeSniffer y luego evaluar los plugins, el código temático, y así sucesivamente para tener una idea de cómo utilizar esto en nuestro trabajo diario en nuestros proyectos de WordPress.

Antes de pasar al siguiente artículo, revisa el código anterior y asegúrate de que tienes instalado PHP y PHP CodeSniffer y que estás familiarizado con su funcionamiento, ya que vamos a atar todo esto.

Por último, puedes revisar todos mis cursos y tutoriales en mi página de perfil, y puedes seguirme en mi blog y/o Twitter en @tommcfarlin donde hablo de varias prácticas de desarrollo de software especialmente en el contexto de WordPress.

Por favor, no dudes en dejar cualquier pregunta o comentario en el feed de abajo, y trataré de responder a cada uno de ellos.