La capacidad de trabajar en equipo o de que el proyecto que estemos desarrollando perdure en el tiempo puede depender en gran medida de cómo hayamos escrito el código y de las facilidades que le demos al que tenga que leer ese código.
Además, escribir todos igual refuerza al propio lenguaje en si en el que trabajamos, el hecho de definir una serie de normas, reglas o estándares a la hora de escribir hacen que el mismo PHP acabe reforzado, ya que cualquier persona de la comunidad puede leer el código.
PSR-2
Aunque no todos los programadores utilizan este estilo de codificación, el estándar más extendido es el PSR-2, si quieres ampliar información sobre qué esto del PSR, en este enlace puedes hacerlo: https://www.startutorial.com/articles/view/modern-php-developer-psr.
Bien, concretando y resumiendo mucho, PSR-2 nos dice exactamente dónde hay que poner las llaves de cada función, con cuántos espacios se tabula el código...
¿Cómo sé que mi código está escrito correctamente?
Utilizaremos una herramienta llamada php-cs-fixer (https://github.com/FriendsOfPHP/PHP-CS-Fixer), y mi recomendación es tenerla instalada en el ordenador en el que desarrolles de forma global, aunque esto ya lo decides tú, si es lo que buscas, sigue estos tres sencillos pasos:
-
$ wget https://cs.symfony.com/download/php-cs-fixer-v2.phar -O php-cs-fixer
-
$ sudo chmod a+x php-cs-fixer
-
$ sudo mv php-cs-fixer /usr/local/bin/php-cs-fixer
Lanzando esos tres comandos, te descargarás primero php-cs-fixer, después lo harás ejecutable y en el tercero creamos el "acceso directo", de esta manera, escribiremos "pcp-cs-fixer" en la línea de comandos desde cualquier ubicación y podremos lanzarlo.
Para comprobar qué ficheros están correctamente escritos lanzaremos el comando:
php-cs-fixer fix PATH --rules=@PSR2 --dry-run
Importante utilizar la opción "--dry-run" para que no se produzcan cambios y en PATH escribir la ruta del proyecto. Este comando nos dirá qué ficheros no están correctamente escritos.
Corrección automática de ficheros con php-cs-fixer
Si lo que deseamos es que la herramienta nos corrija el código, el mismo comando anterior lo podemos lanzar pero sin la opción "dry-run". Mi recomendación es no hacer esto en un proyecto completo, si no corregir ficheros uno a uno para mantener el código que cambia php-cs-fixer más controlado.
php-cs-fixer fix PATH --rules=@PSR2
Ten en cuenta que el parámetro "rules" indica el estándar de codificación por si quieres utilizar otro. También en su repositorio puedes ver las distintas opciones que tiene el comando.
Comprobar el código antes de subir al repositorio
Hasta aquí una breve introducción para entender qué es php-cs-fixer y cómo utilizarlo, pero lo que realmente nos interesa en nuestro día a día es trabajar de una manera ágil, rápida y con todos los automatismos posibles. Y tener que comprobar cada fichero que cambiamos de un proyecto con php-cs-fixer se puede hacer pesado.
Vamos a implementar el hook pre-commit de git, de esta manera cada vez que queramos hacer un commit, no nos lo permitirá si el código de los ficheros cambiados no está en PSR-2. El código del hook será el siguiente:
#!/bin/bash exec 1>&2 ROOT_PATH=$(git rev-parse --show-toplevel) CHANGED_FILES=$(git diff --cached --name-status | awk '$1 != "D" { print $2 }') CS="" for FILE in $CHANGED_FILES ; do if [[ $FILE =~ ^src/.+\.(php|twig|yml|phtml)$ ]]; then CHANGE=$(php-cs-fixer fix $ROOT_PATH/$FILE --rules=@PSR2 --dry-run --using-cache=no | sed '$ d' | cut -d ')' -f 2) if [ ! -z "$CHANGE" ] ; then CS="$CS\n $FILE" fi fi done if [ ! -z "$CS" ] ; then echo -e "The following files do not conform with FIG PSR-2: $CS Fix them in order to commit." for FILE in $CS ; do git reset $FILE done exit 1 fi exit 0
Esto lo guardaremos en un fichero ejecutable dentro de la carpeta del proyecto .git/hooks/pre-commit y se ejecutará automáticamente en cada commit, avisándonos para que corrijamos la codificación de los ficheros que sea necesaria.
Una vez que hayas corregido el estilo del fichero problemático, y te sugiero que lo hagas "a mano", y no pasando el comando php-cs-fixer, para controlar mejor qué código se cambia, tendrás que volver a añadir el fichero al commit con "git add".
¿Cómo corregimos un fichero antiguo que no seguía ningún estilo?
Nos va a pasar a veces que nos encontraremos ficheros que no están en ningún estilo y queremos empezar a aplicarlo. Mi experiencia, para facilitar más tarde la lectura del proceso de desarrollo, dice que hagas un solo commit con la corrección del código, y después apliques los cambios para el correcto desarrollo del proyecto.
De esta manera, cuando veamos el timeline del proyecto veremos dos commits:
- "Corregir codificación del proyecto"
- "Corregir bucle infinito" (por ejemplo)
Mientras que si lo hacemos en un solo commit, no vamos a poder leer los cambios que hicimos en el commit "Corregir bucle infinito" porque el fichero marcará que se cambiaron todas las líneas debido a la corrección de las tabulaciones.