Escribir código para WordPress y que su compañero de equipo le pida constantemente que «limpie los espacios y la indentación» en cada revisión de código, ¿le suena familiar? O quizá su sitio se cae tras una actualización de plugin y no encuentra el error en los registros porque el código se escribió sin ningún estándar consistente.

Este es un escenario conocido para cualquiera que desarrolle WordPress en equipo. Diferentes hábitos de formato, algunos usan condiciones Yoda y otros no, y el escapado de salida falta en algunos puntos.

PHP CodeSniffer resuelve esto automáticamente: verifica su código contra los estándares de codificación de WordPress directamente en su editor, resalta las infracciones y puede corregirlas con un solo comando. A continuación, una guía de configuración desde cero para PhpStorm 2026.

💡 Resumen rápido:

• Instale PHP CodeSniffer y WordPress Coding Standards mediante Composer, ya sea en su proyecto o de forma global
• Establezca la ruta a phpcs en la configuración y añada el estándar de WordPress
• Configure un intérprete remoto de PHP si trabaja a través de Vagrant, Docker o SSH
• Active la inspección de validación PHP CodeSniffer en PhpStorm y los errores se resaltarán sobre la marcha
• Configure el autoformateo mediante PHP Code Beautifier and Fixer para corregir el código con un solo comando

Videotutorial paso a paso en inglés (los mismos pasos que en el texto):

Paso 1: configure un intérprete remoto de PHP

Si desarrolla con PHP local (XAMPP, MAMP, Local, servidor integrado), omita este paso. Para Vagrant, Docker o un servidor remoto vía SSH, necesita especificar el intérprete explícitamente.

Abra Settings → PHP (Ctrl+Alt+S), haga clic en […] junto a CLI Interpreter y seleccione SSH Credentials o Docker Compose.

Complete:

• Dirección IP del host, la misma que usa para el sitio (ping example.dev le ayudará)
• vagrant como nombre de usuario y contraseña (si usa Vagrant)
• /usr/bin/php, ruta al ejecutable de PHP en el servidor

Guarde y seleccione el intérprete creado de la lista:

PhpStorm usará este PHP específico para ejecutar CodeSniffer y otras herramientas de calidad de código.

Paso 2: instale PHP CodeSniffer mediante Composer

El enfoque más fiable es instalar PHPCS como dependencia del proyecto. Añada a su composer.json:

1
{
2
  "require-dev": {
3
    "squizlabs/php_codesniffer": "^3.10"
4
  }
5
}

Luego ejecute composer install. PhpStorm detectará automáticamente phpcs y phpcbf en vendor/bin, por lo que no necesitará establecer las rutas manualmente.

Para instalación global (si lo necesita en todos sus proyectos):

1
composer global require "squizlabs/php_codesniffer=*"

Verifique: el ejecutable phpcs debe estar en ~/.composer/vendor/bin/ (Linux/Mac) o %APPDATA%/Composer/vendor/bin/ (Windows).

Paso 3: instalar los estándares de codificación de WordPress

WPCS es un conjunto de reglas (sniffs) para PHPCS que verifica el cumplimiento específico con los estándares de WordPress: escape de salida, condiciones Yoda, prefijos de funciones y todo lo demás del Manual de estándares de codificación de WordPress.

Vía Composer en su proyecto:

1
composer require --dev wp-coding-standards/wpcs:"^3.0"

O globalmente (el método tradicional y probado):

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

Asegúrese de que el estándar aparezca en ~/.composer/wpcs/ o vendor/wp-coding-standards/wpcs/.

Paso 4: establecer la ruta al estándar en la configuración de PHPCS

Navegue a la carpeta de phpcs y especifique dónde se encuentran los estándares instalados:

1
cd ~/.composer/vendor/bin
2
phpcs --config-set installed_paths ~/.composer/wpcs

Verifique que WordPress aparezca en la lista de estándares disponibles:

1
phpcs -i

La salida debe mostrar cuatro estándares: WordPress, WordPress-Core, WordPress-Docs y WordPress-Extra.

Paso 5: añadir phpcs al PATH

Abra ~/.bash_profile (o ~/.zshrc para ZSH) y añada la línea:

1
PATH=$PATH:~/.composer/vendor/bin

Reinicie su terminal o ejecute source ~/.bash_profile. Ahora el comando phpcs está disponible desde cualquier carpeta.

Pruébelo en cualquier archivo de tema o plugin:

1
cd wp-content/themes/your-theme
2
phpcs --standard=WordPress functions.php

Una salida exitosa se ve así:

Los errores se dividen en dos niveles: ERROR para infracciones graves y WARNING para recomendaciones. Cada línea contiene el número de regla y una descripción del problema.

Paso 6: configurar PHP CodeSniffer en PhpStorm

Abra Settings → PHP → Quality Tools → PHP_CodeSniffer (Ctrl+Alt+S).

Si instaló vía Composer en su proyecto, PhpStorm detectará phpcs desde vendor/bin automáticamente. Si lo instaló globalmente, haga clic en […] junto a Configuration y especifique la ruta al ejecutable: ~/.composer/vendor/bin/phpcs.

Seleccione el intérprete de PHP de la lista, el mismo que configuró en el paso 1.

Paso 7: habilitar la inspección de validación de PHP CodeSniffer

Vaya a Settings → Editor → Inspections, expanda PHP → Quality Tools y marque PHP_CodeSniffer validation.

En el menú desplegable Estándar de codificación, seleccione WordPress. Guarde los ajustes.

A partir de este momento, PhpStorm revisa los archivos PHP abiertos sobre la marcha. Las infracciones se resaltan con subrayados ondulados, igual que los errores habituales del IDE. Pase el cursor sobre ellos y aparecerá una descripción emergente con lo que está mal y cómo solucionarlo.

Paso 8: verifique que funciona

Cree o abra cualquier archivo PHP de un tema y escriba código intencionadamente no estándar:

1
if(true){echo 'Spaces? Never heard of them';}

PhpStorm subrayará la línea: faltan espacios después de if, alrededor de las llaves y dentro de la condición. Pase el cursor y verá el texto del error y el número de regla de WordPress.

Paso 9: configure la corrección automática mediante PHP Code Beautifier and Fixer

No tiene que corregir cada infracción manualmente. PHP Code Beautifier and Fixer (phpcbf) se instala junto con PHPCS y puede corregir código automáticamente según el estándar seleccionado.

Abra Ajustes → PHP → Herramientas de calidad, en la sección Formateadores externos seleccione PHP Code Beautifier and Fixer. Ahora, cuando invoque Código → Reformatear código (Ctrl+Alt+L / Cmd+Option+L), PhpStorm no solo alineará la indentación con su propio formateador, sino que también aplicará las reglas de WordPress mediante phpcbf.

Adicionalmente, configure el estilo de código WordPress para el formateador integrado: Ajustes → Editor → Estilo de código → PHP → Establecer desde → Estilo predefinido → WordPress. De este modo ambas herramientas trabajan en la misma dirección y no entran en conflicto.

Paso 10: qué hacer para proyectos nuevos

Para cada nuevo proyecto WordPress, simplemente repita el paso 1 (intérprete, si es remoto), el paso 6 (configure phpcs en los ajustes) y el paso 7 (active la inspección). Si utiliza Composer en su proyecto, los pasos 2 a 4 se cubren con una sola línea: composer require --dev wp-coding-standards/wpcs.

⁉️🤔 Preguntas frecuentes

¿Cuál es la diferencia entre WordPress, WordPress-Core, WordPress-Docs y WordPress-Extra?

WordPress es el conjunto base de todas las reglas excepto las de documentación. WordPress-Core contiene solo las reglas de la guía oficial de codificación (indentación, nomenclatura, condiciones Yoda). WordPress-Extra añade comprobaciones de seguridad: escape de salida, validación de datos de entrada. WordPress-Docs verifica los estándares de documentación del código (PHPDoc). En la práctica, use WordPress porque incluye Core y Extra.

PhpStorm no detecta phpcs después de la instalación. ¿Qué debo hacer?

Verifique que la carpeta vendor/bin (o ~/.composer/vendor/bin) esté añadida al PATH y contenga el ejecutable phpcs. En PhpStorm, abra Settings → PHP → Quality Tools → PHP_CodeSniffer, haga clic en […] y especifique la ruta a phpcs manualmente. Después de cambiar el intérprete o reinstalar dependencias, puede que necesite restablecer la configuración usando el botón Reset en la misma ventana.

¿Puedo usar PHPCS sin Composer, simplemente descargando el archivo phar?

Sí, pero no lo recomendamos. Al instalar mediante Composer, PhpStorm detecta automáticamente phpcs, phpcbf y todos los estándares registrados. Con el archivo phar, tendrá que establecer las rutas manualmente y gestionar las actualizaciones por separado. Para la colaboración en equipo, una dependencia de Composer en composer.json fija la versión para que todos los desarrolladores tengan el mismo conjunto de reglas.

¿Cómo excluyo archivos o carpetas específicos de la comprobación?

Cree un archivo phpcs.xml en la raíz de su proyecto. Puede excluir directorios (<exclude-pattern>vendor/*</exclude-pattern>), establecer el estándar y cambiar la severidad de reglas individuales. PhpStorm detectará automáticamente este archivo si está en la raíz del proyecto y se llama phpcs.xml o phpcs.xml.dist.

¿Por qué PHPCS se queja de wp_redirect() sin exit?

El estándar de WordPress exige exit o wp_die() después de cualquier redirección: wp_redirect() solo establece la cabecera pero no detiene la ejecución del script. Sin exit, el código posterior a la redirección seguirá ejecutándose, lo cual es un agujero de seguridad. Uso correcto: wp_redirect( home_url() ); exit;.

Qué hacer si su base de código ya es grande y apenas está implementando estándares

Ejecutar PHPCS en un proyecto con miles de infracciones es una forma segura de desmotivar a su equipo. Empiece poco a poco: corrija los errores críticos (error, no advertencia) usando phpcbf y luego reduzca gradualmente el umbral. Añada un phpcs.xml con exclusiones para el código heredado y active nuevas reglas una por una cada mes.

Aquí tiene un plan paso a paso para implementar estándares en un proyecto activo:

• Ejecute phpcs --standard=WordPress --report=summary para ver el número total de errores.
• Corrija automáticamente todo lo posible: phpcbf --standard=WordPress .
• Ordene los errores restantes por severidad, abordando primero los críticos.
• Añada la comprobación a la IC (GitHub Actions, GitLab CI): haga que la compilación falle ante nuevas infracciones en las solicitudes de incorporación de cambios.

Empiece con un composer require --dev wp-coding-standards/wpcs gratuito en un proyecto. Después de una semana, el equipo se habrá acostumbrado al resaltado. Después de un mes, se habrán acostumbrado al código limpio. ¿Qué estándar de codificación usa usted? Compártalo en los comentarios.