Estilo de código en proyectos PHP
Tags: php, codestyle, bestpractices, tools
Published: 2020-07-27 05:13:23

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](https://github.com/FriendsOfPHP/PHP-CS-Fixer).



## 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:

```sh
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](https://github.com/FriendsOfPHP/PHP-CS-Fixer) 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
<?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:

```sh
./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:

```sh
./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:

```json
"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!