Configura Code Sniffer y ESLint para un proyecto de WordPress en 5 minutos

21 ene. 2021

Cuando queremos empezar un proyecto en WordPress, sea un plugin o un tema, puede que nos liemos mucho al empezar configurando todo para que el código esté bonito, cumpla los estándares de WordPress y demás. Pues bien, WordPress ya tiene su propio paquete en npm para instalar casi todo lo que necesitas en un minuto de nada y se llama @wordpress/scripts. Si bien tiene algo de flexibilidad tampoco es la panacea pero se puede usar para empezar muy rápidamente cualquier proyecto.

Instalando @wordpress/scripts

Este paquete trae dentro ESLint, stylelint, Babel y Webpack, que es de lo que nos vamos a ocupar pero también un sistema para test unitarios de JS y end-to-end testing (de lo que me gustaría hablar otro día, linters de JSON y .md y algunas cosas más pero para empezar, esas cuatro cosillas nos vale ya. Empecemos.

Primero creamos un proyecto npm en una carpeta que hayamos creado e instalamos el paquete como dependencia.

npm init
npm install @wordpress/scripts --save-dev

Y ya tenemos a nuestra disposición un montón de scripts. Vamos a abrir package.json y poner lo siguiente en la sección de scripts:

...
"scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js"
  },
...

También necesitaremos crear un fichero .js para crear todo el JS de nuestro proyecto (en la página de documentación de @wordpress/scripts explican cómo crear distintos ficheros JS pero nosotros sólo usaremos uno). @wordpress/scripts por defecto mirará en src/index.js y lo transformará en JS entendible por el ordenador así que podemos escribir JS en ESNext si quisiéramos.

Todos los ficheros transpilados quedarán recogidos en la carpeta build y por cada uno de ellos aparecerá un fichero PHP como asset.index.php que luego podremos usar para encolar los scripts o estilos (hablo de esto más adelante)

npm start comenzará a escuchar los cambios en src/index.js
npm run build transpilará el JS y además lo comprime listo para producción en build.
npm runlint:css: Utilizará stylelint para limpiar el CSS de todo el proyecto acorde a los estándares de código de WordPress
npm runlint:js: Igual pero con ESLint.

PHP Code Sniffer

El paquete que hemos instalado únicamente le falta el PHPCS para limpiar el código PHP acorde a los estándares de WordPress pero tampoco es demasiado difícil:

composer init
composer require wp-coding-standards/wpcs --dev

Y necesitaremos un fichero xml de configuración para phpcs, creamos phpcs.xml con lo siguiente:

<?xml version="1.0"?>
<ruleset name="WP-STARTER-FAST">

	<description>Rules for  a starter project in WordPress.</description>

	<exclude-pattern>node_modules/*</exclude-pattern>
	<exclude-pattern>vendor/*</exclude-pattern>
	<exclude-pattern>build/*</exclude-pattern>

	<config name="installed_paths" value="vendor/wp-coding-standards/wpcs" />
	<arg name="colors"/>
	<arg value="s"/>
	<arg name="extensions" value="php" />

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

Con esto cargaremos las reglas de PHP de WordPress más importantes y le daremos algo de color a la salida de phpcs. Creamos ahora un par de scripts para el linting en PHP dentro de composer.json:

...
"scripts": {
        "lint": "phpcs .",
        "fix": "phpcbf ."
    },
...

Y lo probamos:

composer run-script lint
composer run-script fix

A mí me gusta manejar todo desde un solo sitio como los scripts de npm así que además agrego un par de scripts más a package.json:

"scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "lint:php": "composer run-script lint",
    "fix:php": "composer run-script fix"
  },

Encolando los scripts desde WordPress

La verdad es que podríamos hacer algo así:

wp_enqueue_script( 'index', plugin_dir_url( __FILE__ ) . 'build/index.js' )

Pero el fichero PHP que se ha creado en build es muy útil porque cada vez que el index.js cambia, el index.asset.php un hash distinto para saltarnos la caché del navegador. Es similar a lo que se emplea típicamente en Webpack, con un manifest.json pero algo más simple. Para encolar el build/index.js podemos usar un script como este:

$manifest = plugin_dir_path( __FILE__ ) . 'build/index.asset.php';
	if ( ! is_readable( $manifest ) ) {
		return;
	}

	$asset     = require $manifest;
	$asset_url = plugin_dir_url( __FILE__ ) . 'build/index.js';
	wp_enqueue_script( 'index', $asset_url, $asset['dependencies'], $asset['version'] );

Como vemos, usamos un listado de dependencias que el index.assets.php provee además de el hash o versión del script.

A mí me funciona

Instalando @wordpress/scripts

PHP Code Sniffer

Encolando los scripts desde WordPress