PHP-CS-Fixer para PHP: guía completa con ejemplos

1. ¿Qué es y para qué sirve?

PHP-CS-Fixer (PHP Coding Standards Fixer) es una potente herramienta para formatear automáticamente código PHP según estándares de codificación definidos. Analiza el código fuente, detecta infracciones en las reglas de formato (indentación, espacios, saltos de línea, orden de importaciones, uso de sintaxis corta, etc.) y las corrige de forma automática. Esta biblioteca es un aliado indispensable en proyectos PHP modernos, especialmente en el desarrollo en equipo.

¿Para qué sirve? Primero, para mantener un estilo de código uniforme en el equipo. Cuando varios desarrolladores trabajan en el mismo proyecto, cada uno puede tener sus propios hábitos de formato. PHP-CS-Fixer elimina este problema, unificando todo el código bajo un mismo estándar. Segundo, ahorra tiempo en las revisiones de código (code review): en lugar de discutir sobre espacios o indentaciones, los desarrolladores pueden centrarse en la lógica y la arquitectura. Tercero, el formateo automático evita cambios "ruidosos" en los commits, donde la corrección de una línea puede alterar el formato de todo el archivo.

PHP-CS-Fixer admite más de 100 reglas integradas y también permite crear reglas personalizadas. La herramienta se integra fácilmente en pipelines de CI/CD, sistemas de control de versiones (mediante hooks pre-commit) e IDE. Es compatible con PSR-1, PSR-2, PSR-12, Symfony, Doctrine y otros estándares de codificación populares.

2. Instalación

PHP-CS-Fixer se instala a través de Composer, el gestor de dependencias de PHP. Se recomienda instalarlo de forma global o como dependencia de desarrollo en el proyecto.

# Instalación global (recomendada para usar en cualquier proyecto)
composer global require friendsofphp/php-cs-fixer

# Instalación como dependencia de desarrollo en un proyecto específico
composer require --dev friendsofphp/php-cs-fixer

# Verificar la instalación
php-cs-fixer --version

Después de la instalación global, asegúrate de que el directorio ~/.composer/vendor/bin (o %USERPROFILE%\AppData\Roaming\Composer\vendor\bin en Windows) esté agregado a la variable de entorno PATH.

3. Inicio rápido: ejemplo mínimo funcional

Crea un archivo example.php con código "desordenado":

<?php
$name = "John";
$age=25;
function greet($name){
echo "Hello, ".$name;
}
greet($name);

Ahora dale formato con PHP-CS-Fixer:

php-cs-fixer fix example.php --rules=@PSR12

Después de ejecutarlo, el archivo se verá así:

<?php

$name = 'John';
$age = 25;

function greet($name): void
{
    echo 'Hello, '.$name;
}

greet($name);

Como puedes ver, PHP-CS-Fixer agregó espacios alrededor del operador de asignación, reemplazó las comillas dobles por simples (si no hay interpolación), añadió el tipo de retorno : void, formateó las llaves y agregó líneas en blanco para mejorar la legibilidad.

4. Métodos/funciones/clases principales

4.1. PhpCsFixer\Config::create()

Firma: public static Config::create(): Config

Función: Crea una nueva instancia de configuración para definir las reglas de formato.

<?php
use PhpCsFixer\Config;

$config = Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/src')
    );

4.2. PhpCsFixer\Finder::create()

Firma: public static Finder::create(): Finder

Función: Crea un objeto para buscar archivos PHP que necesiten ser formateados.

<?php
use PhpCsFixer\Finder;

$f