Cómo instalar y usar Codesniffer (phpcs)

¡Hola! En este artículo vamos a aprender a instalar las librerías Coder y Codesniffer (phpcs) a través de composer en nuestra máquina, con los codings standars Drupal y DrupalPractice para usarlo de forma global en todos los proyectos.

Dependiendo de nuestro sistema operativo y versión, las instrucciones pueden ser diferentes. Esta guía detallará cómo llevar a cabo la descarga, instalación y uso para el sistema operativo Ubuntu 24.04 LTS (Linux).

Instalar Coder y Codesniffer

La forma recomendada de instalar estas librerías es a través de Composer, para llevar un control correcto de las versiones y dependencias necesarias; esto nos evitará problemas en el futuro y nos dará facilidades a la hora de obtener las librerías.

¿No estás seguro de si tienes composer instalado? Lanza el siguiente comando:

which composer

Si no localiza la ruta de instalación, tendrás que instalar Composer. Si tienes la última versión estable de Ubuntu (a día de hoy, 24.04 LTS) y los repositorios locales actualizados, basta con lanzar el comando:

sudo apt install composer

Si tienes una versión más antigüa o tienes problemas para obtener Composer por esta vía, sigue las instrucciones de instalación en la página oficial de Composer, para seguir otras alternativas.

Una vez tengamos Composer correctamente instalado en nuestra máquina, pasamos al siguiente paso: descargar e instalar Coder y sus dependencias a través de Composer.

composer global require drupal/coder

Si observas bien, estamos usando el parámetro "global". Esto significa que vamos a instalar el paquete en nuestra máquina local, para su uso global en todos los proyectos. Es importante diferenciar la versión de Composer que tenemos instalada de forma global en nuestro equipo anfitrión y la versión de Composer instalada en cada uno de nuestros proyectos.

En nuestro caso, estamos usando la versión 8.3.x de Coder y la versión 3.11.x de php_codesniffer.

Puedes usar el siguiente comando para determinar la ruta de instalación de cada una de las librerías descargadas por Composer global:

composer global show -P

¡Bien! Ya tenemos instalado Coder y Codesniffer en nuestra máquina, pero nos falta algo. Para no escribir la ruta completa al binario, vamos a agregar la ruta a nuestra variable PATH, con el siguiente comando (comprueba antes que los binarios de Composer realmente se encuentran en esta ruta):

export PATH="$PATH:$HOME/.config/composer/vendor/bin"

Una vez hecho, ya podremos utilizar la herramienta con:

phpcs

Si no encuentra el fichero o directorio, reinicia la terminal. Si sigue sin funcionar, es que la ruta al binario es diferente.

El siguiente paso es comprobar si se han instalado los coding standars que necesitamos para que se valide nuestro código. Podemos comprobar los coding standars con el comando:

phpcs -i

Los coding standars que se utilizan para seguir las buenas prácticas de codificación en Drupal son los perfiles Drupal y DrupalPractice. Se te debería mostrar un mensaje como este:

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, Drupal, DrupalPractice, VariableAnalysis and SlevomatCodingStandard

Si no tienes los conding standars mencionados, deberás realizar una configuración adicional con el siguiente comando:

phpcs --config-set installed_paths ~/.config/composer/vendor/drupal/coder/coder_sniffer,~/.config/composer/vendor/sirbrillig/phpcs-variable-analysis,~/.config/composer/vendor/slevomat/coding-standard

Cómo usar Codesniffer para limpiar y validar código

Existen diferentes formas de usar Codesniffer en el día a día. En esta guía vamos a explicar cómo usarlo a través de la consola por línea de comandos; puedes ver aquí cómo integrarlo en tu IDE.

Análisis de código

Para usar Codesniffer debemos especificar 3 parámetros:

• Los standards de código que queremos aplicar para la revisión automática.
• Las extensiones de ficheros para determinar cuáles serán revisados con el standard definido.
• La ruta del fichero o directorio de ficheros que serán revisados.

Un ejemplo sería el siguiente:

phpcs --standard=Drupal,DrupalPractice --extensions=php,module,inc,install,profile,theme /modules/custom/my_custom_module

Para este caso concreto, Codesniffer realizaría una revisión automática en todos los ficheros de la ruta /modules/custom/my_custom_module cuyas extensiones sean "*.php", "*.module", "*.inc", "*.install", "*.profile", "*.theme" con el coding standard DrupalPractice. 

Cada coding standard tiene una función específica de cara al análisis de código:

• Drupal: revisa el formato y estilo del código, como la indentación, nombres de variables, espacios, estructuras de control...
• DrupalPractice: revisa las buenas prácticas de Drupal, como el uso de APIs de forma correcta, código obsoleto, inyección de dependencias...

Lo ideal es utilizar ambos estándares para realizar un análisis completo del código de tus proyectos. Echa un vistazo a los estándares de código PHP en Drupal.

Cuando ejecutes el comando, se analizará el código del directorio o fichero indicado. Si tienes errores o advertencias, obtendrás un mensaje como este:

FILE: /modules/custom/my_custom_module/src/Controller/MyControllerSample.php
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 7 ERRORS AND 2 WARNINGS AFFECTING 17 LINES
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
   8 | WARNING | [x] Unused use statement
   9 | WARNING | [x] Unused use statement
  56 | ERROR   | [x] Expected 1 space after IF keyword; 0 found
 115 | ERROR   | [ ] unserialize() is insecure unless allowed classes are limited. Use a safe format like JSON or use the allowed_classes option.
 119 | ERROR   | [x] Missing function doc comment
 121 | ERROR   | [x] Line indented incorrectly; expected 6 spaces, found 4
 121 | ERROR   | [x] Object operator not indented correctly; expected 6 spaces but found 4
 122 | ERROR   | [x] Line indented incorrectly; expected 6 spaces, found 4
 123 | ERROR   | [x] Line indented incorrectly; expected 6 spaces, found 4
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 18 MARKED SNIFF VIOLATIONS AUTOMATICALLY

Ahora vamos a explicar cada parte del análisis de código:

• Primero se indica el fichero que se ha analizado, con la ruta completa.
• A continuación se muestra un resumen de los errores y advertencias encontradas.
• Después se muestran los errores y advertencias encontrados, por cada línea, donde se indica:
  • La línea de código, a la izquierda del todo.
  • Si es un error o una advertencia.
  • Un check "X" que, de estar seleccionado, podrá corregirse de forma automática con phpcbf (en el siguiente punto detallamos qué es esto)
  • Una breve descripción que indica por qué se viola el coding standard configurado.
• Un mensaje que muestra cuántos errores o advertencias puede corregir phpcbf.

Como puedes ver, el análisis de código es muy detallado y es sencillo encontrar el lugar y corregir cada uno de los puntos señalados. Lo recomendable aquí es ir corrigiendo cada uno de los puntos, por fichero, e ir lanzando el comando para volver a ejecutar el análisis e ir limpiando los errores y advertencias conforme los vayamos solucionando.

¡Esta es la mejor manera para aprender las prácticas recomendadas y mejorar tu nivel de codificación en el futuro!

Corrección automática con phpcbf

Hay ocasiones en los que se señalan errores o advertencias muy simples o sencillas de solucionar, como por ejemplo un espacio faltante, una tabulación, o un punto al final de un comentario; ¡estos puntos pueden arreglarse de forma automática con phpcbf, la herramienta incluida en Codesniffer!

Para ejecutar phpcbf podemos hacerlo de forma similar a phpcs, de la siguiente manera:

phpcbf --standard=Drupal,DrupalPractice --extensions=php,module,inc,install,profile,theme /modules/custom/my_custom_module/src/Controller/MyControllerSample.php

De esta manera, todos los puntos con una "X" marcada en el análisis de código serán arreglados automáticamente en el fichero especificado en la ruta. ¡Es importante no confundirse con la ruta y las extensiones de fichero!

Conclusión

Usar estas herramientas no solo mejoran la usabilidad y legibilidad del código de tus proyectos, va mucho más allá. Te ayuda a seguir un standard y a crecer como programador, manteniendo un orden y limpieza en tu código y ayudando a tus compañeros de proyectos y a la comunidad a hacer código legible y fácil de entender.