Desarrollo

Automatiza la revisión de estándares de tu código PHP

¿Qué son los estándares PSR y por qué son importantes?

Los estándares PSR (PHP Standard Recommendation) son guías de estilo publicadas por el PHP Framework Interop Group. Vamos, que son unas recomendaciones que hacen quienes más saben de esto sobre cómo «debe» ser tu código.

Como buenos programadores y ordenados que somos todos (por supuesto) es posible que tendamos a pensar que no hay por qué seguir unas reglas que te fijen otros. Son frecuentes expresiones como, «bueno, es mucho más limpio que la llave de inicio de función vaya en la misma línea porque así ocupas menos líneas» (por ejemplo) y es que realmente a lo largo de los años cada uno hemos ido adquiriendo un estilo personal al que estamos acostumbrados.

Lo malo es que en este aspecto los programadores somos cada uno «de su padre y de su madre» y al final los gustos son distintos. Cuando en un proyecto escriben código varios programadores tienes que fijar unas reglas comunes que todos sigan. Si no, al final el código se convierte en ilegible.

Puestos a fijar unas reglas de estilo, antes que fijar las tuyas propias ¿Por qué no usar las recomendaciones oficiales? Y es aquí donde entran en juego los estándares PSR. Además de que, sinceramente, las personas que recomiendan estos estándares saben más que nosotros, puedes encontrar herramientas que te ayuden a automatizar y validar el cumplimiento de los mismos. Lo cual puede resultarte muy útil.

Al tema. ¿ Cómo empiezo a cumplir los etándares PSR en mi código?

La respuesta más obvia a esta pregunta: Conoce las reglas y empieza a aplicarlas.

Ok, esto es importante puesto que según vayas tirando líneas de código ya te tienes que ir acostumbrando a escribir según estos estándares, pero realmente las reglas son muchas. Aquí puedes ver las reglas del estándar PSR2: https://www.php-fig.org/psr/psr-2/. Como ves es un artículo extenso y aplicarlas de memoria es una cuestión de costumbre a lo largo del tiempo.

Lo más recomendable entonces son dos aspectos:

1.- Que tu editor de texto te vaya ayudando y avisando del incumplimiento del estándar.

2.- Disponer de una herramienta que valide e incluso corrija automáticamente tu código.

Revisión de estándares

Existen varias herramientas que nos permiten realizar un revisión de un fichero o un directorio completo. Nosotros recomendamos estas dos:

https://github.com/squizlabs/PHP_CodeSniffer

https://github.com/FriendsOfPHP/PHP-CS-Fixer

Con PHP-CS-Fixer además puedes corregir automáticamente los errores. Ambas son realmente útiles.

Dependiendo del editor de código que uses encontrarás distintas herramientas para validar tu código. En VSCode dispones de múltiples extensiones que te permiten integrar tanto PHP CodeSniffer o PHP-CS-fixer en el editor. Yo uso la siguiente:

https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs

Automatiza la revisión

Aunque estés acostumbrado a programar siguiendo las reglas y aunque tu editor te vaya avisando de los errores, siempre se te va a escarpar alguno. A ti y a cualquiera. Por ello lo mejor es que delegues la responsabilidad del cumplimiento del estándar en un automatismo.

A nosotros se nos ocurrió una buena idea (o eso creemos) que es pasar la revisión automáticamente antes de cada commit que realicemos en Git. Git dispone de un sistema de hooks, que básicamente te permite lanzar ejecutables ante eventos. En este caso realizamos un Pre-commit. Nosotros simplemente hemos creado un script bash PHP que realiza las siguientes acciones:
– Coger los ficheros añadidos o modificados en el commit.
– Pasarles la validación con PHP-CodeSniffer. En caso de que encuentre algún error, el proceso emite una salida de error exit(1). Así git no efectuará el commit.

Para evitarte un buen rato de investigación te dejamos el script aquí, esperamos que te sea útil:

!/usr/bin/php
 <?php
 // Coger qué ficheros se han modificado en el commit
 exec('git diff --name-only --staged --diff-filter=ACMTR', $output); 
 $isViolated = 0;
 $violatedFiles = [];
 $php_cs_path = "/root/.composer/vendor/bin/phpcs"; // Path donde está instalado phpcs
 foreach ($output as $fileName) {
     // Solo procesamos ficheros con extensión PHP
     if (pathinfo($fileName, PATHINFO_EXTENSION) == "php") {
        $psr_output = array();
        // pasamos la validación a cada fichero
        exec("{$php_cs_path} --standard=PSR2 --colors -n {$fileName}", $psr_output, $return);     
        if ($return != 0) {
              $isViolated = 1;
              $violatedFiles[] = $fileName;
              echo implode("\n", $psr_output), "\n";
        }
  }
 }
 if ($isViolated == 1) {
     echo "\n---------------------------- IMPORTANTE ------------------------------------------\n";
     echo "\nUsa las sugerencias de arriba para corregir el código en los siguientes ficheros: \n";
     echo " => " . implode("\n => ", $violatedFiles);
     echo "\n----------------------------------------------------------------------------------\n";
     
     echo "\n----------------------------------------------------------------------------------\n\n\n";
     exit(1);
 } else {
     echo "\n => Commit OK :-)\n\n";
     exit(0);
 }

Puedes colocar este script donde más te convenga, sólo recuerda darle permisos de ejecución. Para que se ejecute antes de cada commit, simplememte crea el archivo: .git/hooks/pre-commit:

#!bin/bash
php PATH_AL_SCRIPT_ANTERIOR

Conclusiones

Como todo, al principio puede costar un poco acostumbrarse a cumplir ciertas reglas que al final «te han sido impuestas», pero acostumbrarte tú y tu equipo a cumplir estos criterios os ayudará a tener un código mucho más limpio y legible.

Con las herramientas que os recomendamos aquí y con las automatizaciones adecuadas no se hace algo tedioso, y con el tiempo las reglas van entrando en tu cabeza de una forma natural.

En definitiva, nos parece muy recomendable hacer cumplir el estándar, y los resultados son muy positivos.

Esperamos que te sea útil!!

DEJA UNA RESPUESTA

Tu dirección de correo electrónico no será publicada.