Estilo de código en proyectos PHP

Una de las mejores maneras de mantener un código legible a lo largo del tiempo es definir estándares de estilo, con esto me refiero a; por ejemplo:

• Definir que las clases se deben declarar utilizando StudlyCaps.
• Se deben utilizar 4 espacios para identar el código.
• No se deben dejar líneas en blanco después de abrir una llave.
• entre otros...

Y aunque parece trivial el hecho de seguir estas convenciones, en ocasiones podemos cometer algún error, ya sea por la velocidad del desarrollo, desconocimiento de los estándares o simplemente por pereza. Por fortuna para nosotros existen herramientas automatizadas que nos permiten "forzar" a que el código siga nuestras convenciones iniciales, tal es el caso de PHP Code Sniffer.

Uso

PHP sniffer es una librería que se encarga de la validación de sintaxis del código (también conocido como estilo de código), la librería está configurada para seguir con los estándares oficiales definidos en https://www.php-fig.org/psr/ (apartados PSR-1 y PSR-12), sin embargo, tiene flexibilidad para que puedas modificar esas reglas y configurarlas de tal manera que se adapte a los estándares de tu proyecto.

Una ventaja de utilizar code sniffer es que a demás de validar la sintaxis, cuenta con una utilidad que puede corregir algunos de los errores detectados por la misma herramienta.

Instalación y configuración

Si estás utilizando composer, bastará con ejecutar la siguiente instrucción en tu terminal, en la raíz de tu proyecto:

composer require --dev friendsofphp/php-cs-fixer

Nota: En caso de no utilizar composer, code sniffer cuenta con ejecutable .phar además de otros métodos de instalación, te recomiendo visitar el repositorio oficial que mantendrá actualizada la guía de instalación para cada caso.

Se utiliza la bandera --dev ya que la validación del estilo de código solamente se realiza durante la etapa de desarrollo.

Una vez instalada la libreŕia, se puede utilizar ejecutando la siguiente línea:

php ./vendor/bin/ {SRC_FOLDER}

En dónde:

• SRC_FOLDER: Es el directorio que queremos que se analizado por phpcs.

Al igual que las librerías de complemento del proyecto, se puede crear un archivo para configurar las reglas necesarias, en el caso de phpcs la configuración se realiza en php aunque el archivo de configuración no lleve como tal la extensión php.

Para poder configurarlo podemos crear en el directorio raíz un archivo llamado .php_cs o .php_cs.dist, con algo similar a lo siguiente:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in('DIRECTORIO_DEL_PROYECTO');

return PhpCsFixer\Config::create()
    ->setRules([
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder($finder);

En dónde:

• $finder: Es un objeto en dónde podemos definir los archivoso directorios que queremos que sean analizados por phpcs, se crea utilizando el objeto PhpCsFixer\Finder y en él puedes encadenar los métodos in(DIRECTORY) para establecer el directorio del proyecto, y el método exclude(DIRECTORY) si deseas excluir algunos archivos.

Nota: DIRECTORY, es un string, y por lo regular, el método puede tener como parámetro la constante mágica __DIR__ haciendo referencia al directorio actual.

• El archivo debe regresar una instancia del objeto PhpCsFixer\Config el cual contiene todas las reglas que se desean agregar al verificador de estilos. Nuevamente reitero que se siguen las convenciones más recientes, pero eres libre de agregar en el método setRules() todas las reglas que necesites, para que phpcs se adapte a su proyecto.

• No encadenar el método setFinder a la instancia de PhpCsFixer\Config , para decírle los directorios que debe analizar y/o excluir.

Ejecución de phpcs

Una vez configurado phpcs con las reglas que deseemos y archivos que deben ser analizados, entonces tenemos un par de comandos que se encargarán de ejecutar la herramienta de phpcs:

Revisión de estilos

Bastará con ejecutar la instrucción:

./vendor/bin/php-cs-fixer fix -v --diff --dry-run

En dónde:

• fix: Es la instrucción que se encarga de ejecutar el análisis de los estilos del código.
• -v: Le indica a phpcs que muestre la mayor cantidad de información posible respecto a su ejecución.
• --diff: Le indica a phpcs que nos muestre las diferencias encontradas en cada archivo.
• --dry-run: Le indica a phpcs que el comando debe ejecutarse sin realizar ningún cambio en los archivos analizados.

Al finalizar el proceso, phpcs te entregará una salida en la que cada archivo analizado se puede representar con los valores:

? = Pasó algo inesperado.
I = Sintaxis de php incorrecta, se saltará la revisión.
S = Archivo saltado, por estar vacío o por ya estar en caché.
. = No requiere cambios.
F = Arreglado.
E = Archivo que tiene errores de estilo.

A parte de darte una representación rápida de cada archivo, el comando hará una lista de los errores que se detectaron en cada archivo.

Nota: phpcs utiliza un sistema de caché para no tener que analizar aquellos archivos que ya fueron analizados y que no tienen cambios. Si tu proyecto es muy extenso, es muy probable que éste proceso demore un buen rato.

Corrección de estilos

Parte de la magia de phpcs no es solo asegurarse de que las reglas se cumplan, sino que tiene la capacidad de corregir de manera automática aquellos errores que se detectaron durante el análisis, para ello, se ejecuta el siguiente comando:

./vendor/bin/php-cs-fixer fix -v --diff

Si nos damos cuenta, el comando es muy similar al anterior, pero eliminado la opción --dry-run, de ésta manera phpcs intentaŕa agregar los estilos erróneos que detecte.

Una vez terminado el proceso, obtendremos una salida similar a la del comando anterior.

Creando un alias para ejecutar phpcs (solo composer)

Ahora bien, es muy probable que pienses que los comandos son un poco difíciles de memorizar, por fortuna para nosotros, si es que utilizamos composer, es que podemos crear un script personalizado que haga más fácil la ejecución de cualquier herramienta externa, nosotros crearemos 2, una para revisar el código y otra para corregirlo.

Para ello, basta con abrir el archivo composer.json , y agregar una nueva entrada llamada "scripts", similar a lo siguiente:

"scripts": {
    "phpcs": "php-cs-fixer fix -v --diff --dry-run",
    "phpcs-fix": "php-cs-fixer fix -v --diff"
},

Una vez realizados los cambios, guardamos el archivo y podremos ejecutar los comandos:

• composer phpcs para hacer la revisión del código
• composer phpcs-fix para intentar solucionar los errores de manera automática.

Conclusión

Una de las principales ventajas de phpcs , a parte de ayudar mantener el código igual a lo largo de todo su desarrollo, es que se presta perfectamente para un proceso de integración continua, por ende, te permite que tu proyecto pueda ser construido por varios programadores y que en caso de no cumplir con las reglas, el código no se podrá integrar al proyecto.

Y a pesar de que phpcs tiene una herramienta que te permite corregir los estilos automáticamente, yo te sugiero que intentes escribir código que no tenga errores de estilo (sin la necesidad de usar la herramienta de corrección). Esto te ayudará a mejorar tu calidad de código en general.

Espero que este post te haya sido de utilidad, recuerda que si tienes alguna duda o comentario que pueda mejorar el contenido, siéntete libre de compartirlo en los comentarios, puedes expresarlo en los comentarios.

¡Hasta la próxima!