Utilizando PHPCS y los estándares WordPress

Es muy importante que cuando escribimos código para nosotros o para nuestros clientes, utilicemos unos estándares.

Esto de por si sólo no nos garantiza un buen código o incluso que sea correcto, pero al menos hace nuestro código más legible para nosotros en el futuro o para cualquier otro programador que tenga que modificarlo. Ya hablé acerca de esto hace cerca de tres años en la entrada Por qué no debemos usar código espagueti en WordPress.

Hace un par de días, en la entrada Mis herramientas para el trabajo diario 2020 os contaba como instalar PHPCS, pero voy a recordaros el proceso con algunas modificaciones y más completo.

Instalando PHPCS y los estándares

Lo primero que haremos es descargar PHP en local, necesario para algunas herramientas.

En mi caso utilizo Windows, que es lo que indicaré, pero el proceso para iOS y Linux es similar.

Descargo la versión 7.4.7 y la descomprimo en la unidad C en el directorio c:\php

Añado PHP a las variables de entorno del sistema desde Configuración → Acerca de → Información del sistema → Configuración avanzada del sistema → Variables de entorno y ahí en Variables del sistema añado c:\php al path.

Compruebo que está todo correcto ejecutando una consola y desde cualquier directorio veo que php -v devuelve la información de versión correcta.

Continúo instalando Composer para la administración de paquetes de PHP. Desde cualquier directorio compruebo que se ejecuta correctamente Composer mirando su versión con composer --version (actualizamos composer con composer self-update)

Instalo globalmente PHP Code Sniffer (phpcs) directamente desde composer con el comando:

# composer global require "squizlabs/php_codesniffer=*"

y de nuevo compruebo que funciona desde cualquier directorio devolviendo su versión con phpcs --version

Estas comprobaciones de comandos las realizo desde la consola cmd, la consola PowerShell y desde la consola Bash de Git. Evidentemente desde WSL no funcionará a no ser que realicemos la instalación en nuestro Ubuntu, ya que es un subsistema diferente.

Ahora instalamos los estándares de WordPress para phpcs, para lo que primero compruebo los estándares instalados con phpcs -i y veo que no están los de WordPress.

En mi carpeta de perfil (o en otra que queráis) creo una nueva carpeta para mis nuevos estándares de phpcs que le llamo phpcs_standards quedando C:\Users\carlos\phpcs_standards\wpcs

Entro en dicha carpeta y clono el repo por ejemplo en la carpeta wpcs con el comando:

# git clone https://github.com/WordPress/WordPress-Coding-Standards wpcs

y después añado el path a phpcs con el comando:

# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs

Es importante en Windows usar la doble barra, sino estaremos escapando el caracter después de la barra invertida.

Y vuelvo a comprobar de nuevo con phpcs -i

Ahora que ya tengo configurados los estándares de WordPress, voy con la compatibilidad para las versiones de PHP, para lo que realizo el mismo procedimiento que al instalar las reglas de compatibilidad de WordPress.

Clono el repo por ejemplo en la carpeta phpc con el comando:

# git clone https://github.com/PHPCompatibility/PHPCompatibility phpc

Compruebo la configuración de phpcs, sobre todo para ver el path (añadido previamente), ya que el parámetro --config-set installed_pathssobreescribe cualquier valor previo:

# phpcs --config-show

y después añado el path a phpcs con el comando:

# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc

en esta ocasión le paso el path anterior y después de la coma el nuevo path. Vuelvo a comprobar de nuevo con phpcs -i

Pero es que además tenemos el proyecto PHPCompatibilityWP que además de comprobar la compatibilidad de PHP, lo hace específico para WordPress excluyendo los back-fills y poly-fills proporcionados por WordPress.

Vamos a instalarlo igual que antes, clonando el repo, pero primero vemos que entre sus requisitos están PHP_CodeSniffer que ya tenemos instalado, PHPCompatibility que también tenemos instalado y PHPCompatibilityParagonie que vamos a instalar junto con este repo.

Ejecutamos lo siguiente:

# git clone https://github.com/PHPCompatibility/PHPCompatibilityParagonie phpcp
# git clone https://github.com/PHPCompatibility/PHPCompatibilityWP phpcwp
# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc,C:\\Users\\carlos\\phpcs_standards\\phpcp,C:\\Users\\carlos\\phpcs_standards\\phpcwp

Y volvemos a comprobar que ya están instalados los estándares con phpcs -i

Podemos por ejemplo comprobar desde línea de comandos la compatibilidad de nuestros archivos con extensión php con el siguiente comando:

# phpcs -p *.php --standard=PHPCompatibilityWP

Aunque lo ideal es ir comprobando directamente sobre la marcha desde el propio editor.

Actualizando PHPCS y los estándares

Para actualizar phpcs ejecutamos:

# composer global require squizlabs/php_codesniffer

Para actualizar los estándares de WordPress entramos en el directorio en el que clonamos los estándares y obtenemos la última versión:

# cd C:\Users\carlos\phpcs_standards\wpcs
# git pull

Para actualizar PHP Compatibility realizamos el mismo proceso en el directorio sobre el que clonamos:

# cd C:\Users\carlos\phpcs_standards\phpc
# git pull

Los mismo con PHPCompatibilityWP y PHPCompatibilityParagonie:

# cd C:\Users\carlos\phpcs_standards\phpcp
# git pull
# cd C:\Users\carlos\phpcs_standards\phpcwp
# git pull

Si al comprobar la compatibilidad de versiones de PHP os da el error phpcs: Referenced sniff «PHPCS23Utils» does not exist cambiad la rama del repo PHPCompatibility a master y se debería solucionar el problema (cambiamos a master tanto en wpcs como en phpc con git switch master).

Excepciones de reglas

Si queremos que no se nos avise de algún error, como por ejemplo el no utilizar una versión en nuestros scripts u hojas de estilos para evitar el query string con el número de versión en nuestro archivo; primero podemos ver que regla deberemos ignorar, ejecutando pcpcs para nuestro archivo con el estándar de WordPress:

# phpcs -s --standard=WordPress-Extra nuestro-archivo.php

Y nos mostrará al final y entre paréntesis la regla que deberemos ignorar, en nuestro caso WordPress.WP.EnqueuedResourceParameters.MissingVersion que pondremos en nuestro archivo phpcs.ruleset.xml de nuestro proyecto:

<rule ref="WordPress-Extra">
	<exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion" />
</rule>

Para que nos vaya mostrando los errores de los estándares según vamos escribiendo en nuestro editor (en mi caso Visual Studio Code), si tenemos todo bien configurado, sólo debemos instalar la extensión en el editor, en este caso la que se llama phpcs.

Disponemos de varias opciones de configuración, que recordad, podemos aplicarlas globalmente para todos nuestros proyectos o para un proyecto en concreto.

Y para finalizar os dejo un ejemplo de un archivo de configuración de reglas de phpcs para un plugin de WordPress que comprueba que el text_domain sea siempre cl-menu-cache, además ignoro la versión faltante al encolar archivos CSS y JS (mejor para caché y algo que nos piden muchos comprobadores de optimización WPO) y pruebo la compatibilidad de versiones de PHP desde la 7.4 en adelante:

<?xml version="1.0"?>
<ruleset name="CL Menu Cache WordPress Plugin Coding Standards">

	<description>A custom set of code standard rules to check for WordPress plugin CL Menu Cache.</description>

	<rule ref="WordPress-Core" />
	<rule ref="WordPress-Docs" />
	<rule ref="WordPress-Extra" />

	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array" value="cl-menu-cache" />
		</properties>
	</rule>

	<rule ref="WordPress-Extra">
		<exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion" />
	</rule>

	<!-- Run against the PHPCompatibilityWP ruleset -->
	<rule ref="PHPCompatibilityWP"/>

	<!-- Check for cross-version support for PHP 7.4 and higher -->
	<config name="testVersion" value="7.4-"/>

	<exclude-pattern>*/*.txt</exclude-pattern>
	<exclude-pattern>*/docs/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/vendor/*</exclude-pattern>
</ruleset>

Actualización 12/07/2023

Si phpcs nos da un error de ERROR: Referenced sniff "Universal.WhiteSpace.DisallowInlineTabs" does not exist deberemos de ir al directorio donde tenemos instalados los estándares de WordPress (wpcs si seguimos las indicaciones anteriores) y cambiar a la rama principal (master en este caso con git switch master) y ya nos debería funcionar sin error:

Actualización 21/07/2023: WooCommerce

Instalamos los estándares de WooCommerce, aunque lo ideal sería mediante composer tal como se indica en el repo, vamos a continuar como los anteriores:

# git clone https://github.com/woocommerce/woocommerce-sniffs/ woocs
# phpcs --config-set installed_paths C:\\Users\\carlos\\phpcs_standards\\wpcs,C:\\Users\\carlos\\phpcs_standards\\phpc,C:\\Users\\carlos\\phpcs_standards\\phpcp,C:\\Users\\carlos\\phpcs_standards\\phpcwp,C:\\Users\\carlos\\phpcs_standards\\woocs\\src

En este caso la ruta a añadir lleva src al final de la misma.