Etiqueta: prettier-php

El código PHP desordenado ralentiza a los equipos más de lo que la mayoría espera. Un espacio faltante no hará fallar la producción, pero un formato inconsistente crea fricción en las revisiones de código, complica las fusiones y hace que incluso archivos simples sean más difíciles de confiar.

Un buen formateador de PHP resuelve eso al sacar las decisiones de estilo de manos humanas. En lugar de debatir la colocación de llaves o el ajuste de líneas en cada solicitud de extracción, usted define las reglas una vez, ejecuta la herramienta automáticamente y mantiene el código limpio desde ese momento.

Para desarrolladores individuales, eso significa trabajo más rápido y menos distracciones. Para agencias, startups y equipos de ingeniería más grandes, significa código consistente, diffs estables, incorporación más fácil y pipelines de CI/CD más suaves. La mejor parte es que las herramientas de formateo de PHP más potentes son gratuitas, de código abierto o ya están incluidas en flujos de trabajo que podría estar usando hoy; véase herramientas para ejemplos.

Qué es un formateador de PHP y por qué importa

Un formateador de PHP es una herramienta que reescribe tu código para que siga un estilo consistente. Maneja la indentación, el espaciado, los saltos de línea, la colocación de llaves, el orden de importaciones y otras reglas de diseño. El objetivo no es cambiar lo que hace el código, sino cambiar su apariencia para que los humanos lo lean más fácilmente.

Eso diferencia a un formateador de un linter o un analizador estático. Un formateador se centra en la presentación y el estilo, un linter revisa problemas de sintaxis y violaciones de reglas, y un analizador estático profundiza para buscar problemas de tipos, código muerto, lógica arriesgada y problemas arquitectónicos. En la práctica, flujos de trabajo sólidos de PHP a menudo usan los tres.

La razón por la que el formateo importa es simple. Los equipos leen código mucho más a menudo de lo que lo escriben. Una base de código con un estilo consistente se siente predecible. Puedes escanear funciones más rápido, comparar cambios de forma más limpia y dedicar el tiempo de revisión de código a la arquitectura o a los errores en lugar de discutir sobre pestañas frente a espacios. Esto es especialmente valioso en proyectos de código abierto, en la transferencia al cliente, en repositorios empresariales y en cualquier configuración con ganchos de Git automáticos o comprobaciones de CI. Si varios colaboradores tocan el mismo código cada semana, un formateador se paga solo rápidamente.

Cómo funciona el formateo de PHP: principios y reglas clave

La mayoría de los formateadores modernos de PHP leen tus archivos como tokens, y algunas herramientas operan más cerca de estructuras de sintaxis analizadas. No realizan simplemente sustituciones de texto ciegas. Inspeccionan el código, entienden dónde comienzan y terminan palabras clave, operadores, cadenas, comentarios y bloques, y luego reescriben el archivo según las reglas configuradas.

Por eso un formateador adecuado puede normalizar de forma segura código que incluye sintaxis compleja como clases anónimas, tipos de unión, atributos, expresiones match, bloques heredoc y nowdoc, y características del lenguaje PHP 8 o superiores. Un formateador débil rompería estos casos. Uno maduro los maneja de forma predecible.

Reglas básicas de formateo

A nivel práctico, la mayoría de los formateadores aplican las mismas familias de reglas. Normalizan la indentación, la colocación de llaves, el espaciado alrededor de los operadores, los saltos de línea, el formateo de matrices y el orden de importaciones. Muchas herramientas también eliminan importaciones no utilizadas, alinean sentencias en varias líneas y estandarizan las líneas en blanco entre los miembros de la clase. Una cualidad clave a buscar es la idempotencia. Eso significa que si ejecuta el formateador dos veces, la segunda ejecución no debería generar cambios adicionales. Las herramientas idempotentes crean diffs estables, reducen el ruido en las solicitudes de extracción y hacen que las ejecuciones de CI sean más confiables.

Estándares PSR y guías de estilo

En el ecosistema de PHP, PSR-1, PSR-2 y, especialmente, PSR-12 son las referencias de estilo más conocidas. PSR-12 es la línea base moderna con la que muchos equipos comienzan porque ofrece una estructura ampliamente aceptada para formateo y distribución. Los formateadores más fuertes permiten empezar con PSR-12 y luego superponer preferencias personalizadas, como el orden de importaciones, comas finales o el envolvimiento de argumentos.

Formato determinista frente a configurable

Algunas herramientas son muy opinadas y buscan producir una única salida predecible. Otras son altamente configurables y permiten a los equipos ajustar decenas de reglas. Si trabajas con un equipo pequeño o trabajas solo, un formateador con una postura opinada puede ahorrar tiempo porque reduce la fatiga de decisiones. Si mantienes una aplicación heredada o necesitas coincidir con una guía de estilo interna existente, una herramienta más configurable suele ser la opción más adecuada.

1. PHP-CS-Fixer

PHP-CS-Fixer es una de las herramientas de formateo de PHP más utilizadas, y con buena razón. Es rápida, madura y altamente configurable, creada específicamente para hacer cumplir y corregir los estándares de codificación en proyectos PHP. Si desea un formateador serio que pueda escalar desde un proyecto personal hasta una gran base de código de producción, esta suele ser la primera herramienta a evaluar.

Lo que hace que PHP-CS-Fixer se destaque es su equilibrio entre presets razonables y una personalización profunda. Puede comenzar con un conjunto de reglas como @PSR12, luego agregar o eliminar fixers individuales a medida que su equipo refina su estilo. Esa flexibilidad es útil para agencias, equipos de productos y mantenedores de bases de código de larga duración que requieren consistencia sin perder el control. Las características clave incluyen conjuntos de reglas configurables basados en PSR y presets de la comunidad, corrección automática de código, salida de dif para revisar los cambios antes de confirmar, soporte de caché para acelerar ejecuciones repetidas y buena compatibilidad con CI y ganchos de Git.

PHP-CS-Fixer es muy flexible para convenciones de equipo personalizadas, excelente para la automatización en hooks de pre-commit y CI, y ampliamente adoptado con un sólido soporte del ecosistema. Puede resultar abrumador si es nuevo en las reglas de formateo, y algunos fixers arriesgados requieren pruebas cuidadosas antes de una adopción general. El precio es simple: PHP-CS-Fixer es libre y de código abierto.

2. PHP_CodeSniffer y phpcbf

PHP_CodeSniffer, comúnmente conocido como phpcs, es conocido principalmente por detectar violaciones de estándares de codificación. Su herramienta compañera, phpcbf, puede corregir automáticamente muchas de esas violaciones. Juntas, forman un sólido flujo de trabajo de cumplimiento de estándares para equipos que se preocupan profundamente por el cumplimiento de reglas y la auditoría.

Este par es especialmente útil cuando tu proyecto necesita reportar problemas de estilo tanto como necesita corregirlos. En muchas organizaciones, phpcs actúa como el guardián de estándares en CI, mientras que phpcbf maneja la limpieza automática cuando es posible. Si tu flujo de trabajo se apoya fuertemente en estándares y conjuntos de reglas formales, esta cadena de herramientas merece una consideración seria. Las capacidades clave incluyen validación basada en conjuntos de reglas mediante configuración XML, soporte para estándares oficiales como PSR-12, correcciones automáticas a través de phpcbf, una sólida integración con editores y CI, y reportes detallados para equipos que desean visibilidad de las violaciones.

phpcs es excelente para la aplicación y auditoría, con informes claros en entornos de equipo y buena idoneidad para CI. Las desventajas son que la cobertura de auto-arreglo puede ser más estrecha que PHP-CS-Fixer para algunas preferencias de estilo, y la configuración se siente más orientada a estándares que a formateo. PHP_CodeSniffer es libre y de código abierto.

3. Prettier Plugin PHP

Prettier Plugin PHP trae la filosofía de Prettier a PHP. Si su proyecto ya utiliza Prettier para JavaScript, TypeScript, CSS, Markdown o JSON, agregar el formateo de PHP a través del mismo flujo de trabajo centrado en el estilo puede resultar atractivo. Su mayor fortaleza es la consistencia en repositorios multilenguaje. Los equipos pequeños de producto y los freelancers de pila completa a menudo prefieren una mentalidad de formateo única en toda la pila en lugar de mantener hábitos separados para archivos de frontend y back-end. Las desventajas clave son que no es tan específico de PHP en la personalización como PHP-CS-Fixer y puede que no se alinee con todas las guías de estilo heredadas de PHP. Prettier y su complemento PHP suelen ser gratuitos y de código abierto.

4. Formateador incorporado de PhpStorm

Si tu equipo trabaja principalmente dentro de PhpStorm, el formateador incorporado puede ser sorprendentemente efectivo. JetBrains ofrece controles detallados de estilo de código, soporte de inspecciones y acciones de ahorro de tiempo que hacen que el formateo en tiempo real se sienta fluido. Esta es una opción sólida para desarrolladores que desean retroalimentación inmediata en el editor y una experiencia IDE pulida. Sin embargo, depender únicamente del formateo del IDE puede generar deriva si no todos usan la misma versión y configuración, por lo que los equipos normalmente emparejan PhpStorm con un formateador de CLI en CI. El IDE ofrece una excelente experiencia de editor, formateo en tiempo real y configuraciones detalladas, pero es mejor para equipos estandarizados en PhpStorm y requiere disciplina de configuraciones compartidas para evitar inconsistencias. PhpStorm es un IDE comercial de pago, aunque JetBrains ofrece pruebas y programas de licencias.

5. Formateadores PHP en línea

Las herramientas de formateo en línea para PHP son útiles cuando necesita una limpieza rápida, quiere inspeccionar la salida de estilo o está ayudando a un cliente o a un desarrollador junior a entender los cambios de formateo sin configurar un entorno local. Pueden ser convenientes para fragmentos pequeños y experimentos rápidos, pero no son la mejor base para flujos de trabajo profesionales. Para repositorios de producción, las herramientas locales y las integradas en CI son mucho más confiables, porque desea una configuración versionada, salida reproducible y controles de privacidad si el código es propietario o sensible. Los formateadores en línea son rápidos y fáciles para fragmentos pequeños, no requieren instalación y son útiles para experimentos rápidos, pero a menudo carecen de garantías de privacidad, bloqueo de versiones y disponibilidad a largo plazo. Los precios varían, y muchos formateadores en línea son gratuitos para usar con garantías limitadas.

Comparación de las opciones de formateadores de PHP más populares

Para la mayoría de los casos de uso profesionales, la decisión real se reduce a PHP-CS-Fixer frente a PHP_CodeSniffer/phpcbf, con Prettier Plugin PHP entrando en juego cuando el repositorio está fuertemente mezclado en lenguajes. La diferencia fundamental es la siguiente: PHP-CS-Fixer suele ser la mejor herramienta de formateo puro, mientras que phpcs + phpcbf suele ser la mejor herramienta para el cumplimiento de estándares. Eso no significa que una reemplace a la otra en todas las configuraciones. Muchos equipos ejecutan el formateo con una herramienta y la validación con otra.

Herramienta	Mejor para	Fortaleza	Compromiso
PHP-CS-Fixer	Equipos que desean formateo flexible y automatizado	Personalización rica de reglas y autocorrección fuerte	Requiere decisiones de reglas y bloqueo de versiones
PHP_CodeSniffer + phpcbf	Equipos que hacen cumplir estándares formales en CI	Informes sólidos y verificaciones de estándares	La corrección puede ser menos flexible en algunos casos
Prettier Plugin PHP	Repositorios JS/PHP mixtos	Formato consistente entre lenguajes	Menor personalización específica de PHP
PhpStorm Formatter	Flujos de trabajo centrados en IDE	Gran experiencia de desarrollo local	Necesita respaldo CLI/CI para coherencia del equipo
Formatters en línea	Limpieza rápida de fragmentos	Comodidad instantánea	No apto para flujos de trabajo serios de equipo

Elegir el formateador adecuado para su proyecto

El mejor formateador de PHP es aquel que su equipo realmente utilizará de forma constante. Suena obvio, pero muchos proyectos eligen una herramienta poderosa, nunca terminan la configuración o nunca la conectan con Git y CI. Si eres un desarrollador individual o freelancer, PHP-CS-Fixer suele ser la opción predeterminada más simple y sólida porque es fácil de automatizar, se alinea bien con PSR-12 y te da margen para crecer. Si trabajas en un equipo que ya utiliza estándares de codificación formales, PHP_CodeSniffer más phpcbf puede encajar mejor porque combina verificación y corrección en un flujo de trabajo orientado a la conformidad.

Qué considerar antes de elegir: el tamaño del equipo afecta cuán estricto y automatizado debe ser su configuración, las guías de estilo existentes importan porque cambiar convenciones en un repositorio maduro puede generar diff s ruido, las necesidades de CI importan porque el formateo local por sí solo no garantiza la consistencia, y el tamaño del repositorio importa porque el rendimiento y el caché se vuelven más notorios en monorepos grandes. Bloquee las versiones del formateador en Composer o en su configuración de herramientas, confirme el archivo de configuración en el repositorio y pruebe los cambios de formato antes de implementarlos ampliamente. Un formateador debe generar confianza, no sorpresas.

Paso a paso: Configuración de PHP-CS-Fixer

PHP-CS-Fixer es un buen punto de partida porque maneja flujos de trabajo de formateo simples y avanzados de manera efectiva. La configuración es directa y, una vez que está en funcionamiento, el uso diario se vuelve automático.

Instalación vía Composer

Si su proyecto utiliza Composer, instálelo como una dependencia de desarrollo:

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

También puede usar la distribución PHAR si prefiere un binario independiente, pero Composer suele ser la opción más sencilla para los equipos porque mantiene la versión fijada en el proyecto.

Crear una configuración básica

Un archivo mínimo .php-cs-fixer.php que use PSR-12 podría verse así:

<?php
$finder = PhpCsFixerFinder::create()
    ->in(__DIR__ . '/src')
    ->in(__DIR__ . '/tests');
return (new PhpCsFixerConfig())
    ->setRules([
        '@PSR12' => true,
    ])
    ->setFinder($finder);

Si desea una configuración ligeramente más personalizada, puede extenderla:

<?php
$finder = PhpCsFixerFinder::create()
    ->in([__DIR__ . '/src', __DIR__ . '/tests'])
    ->exclude(['vendor', 'storage', 'cache']);
return (new PhpCsFixerConfig())
    ->setRiskyAllowed(false)
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
        'ordered_imports' => true,
        'no_unused_imports' => true,
        'trailing_comma_in_multiline' => true,
    ])
    ->setFinder($finder);

Esto le ofrece una base práctica sin volverse demasiado rígido demasiado pronto.

Ejecutar localmente y revisar difs

Para corregir archivos:

vendor/bin/php-cs-fixer fix

Para obtener una vista previa de los cambios con mayor visibilidad:

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

Ese modo de ejecución en seco es valioso en CI porque le indica si el código es conforme sin reescribir archivos en la pipeline.

Añadir un gancho pre-commit

Un sencillo gancho pre-commit de Git puede evitar que PHP sin formatear llegue al repositorio:

#!/bin/sh
vendor/bin/php-cs-fixer fix --quiet
git add .

En un flujo de trabajo maduro, a menudo limitaría el alcance a los archivos PHP que ya están en la zona de staging, pero incluso un gancho básico puede mejorar drásticamente la consistencia.

Ejemplo de GitHub Actions

Para GitHub Actions, una comprobación de formateo simple podría verse así:

name: PHP Formatting
on: [push, pull_request]
jobs:
### php-cs-fixer:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
### with:
          php-version: '8.2'
      - run: composer install --no-interaction --prefer-dist
      - run: vendor/bin/php-cs-fixer fix --dry-run --diff

Ejemplo de GitLab CI

Para GitLab CI, el equivalente es igual de directo:

php_cs_fixer:
  image: php:8.2
### script:
    - apt-get update && apt-get install -y git unzip
    - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
    - php composer-setup.php
    - php composer.phar install --no-interaction --prefer-dist
    - vendor/bin/php-cs-fixer fix --dry-run --diff

Utilice caché si su proyecto es grande. En repositorios grandes, eso puede reducir notablemente los tiempos de ejecución repetidos.

Paso a paso: Uso de PHP_CodeSniffer y phpcbf

Si PHP-CS-Fixer parece orientado al formateo, PHP_CodeSniffer parece orientado a estándares. Eso no es una debilidad. En muchas organizaciones, ese es precisamente el punto.

Instalar y ejecutar comprobaciones básicas

Instálelo con Composer:

composer require --dev squizlabs/php_codesniffer

Ejecute una verificación PSR-12 básica:

vendor/bin/phpcs --standard=PSR12 src tests

Si las violaciones son corregibles automáticamente, use phpcbf:

vendor/bin/phpcbf --standard=PSR12 src tests

Crear un conjunto de reglas personalizado

Un archivo phpcs.xml o ruleset.xml simple le ofrece una aplicación repetible de estándares:

<?xml version="1.0"?>
<ruleset name="ProjectStandard">
    <description>Project coding standard</description>
    <rule ref="PSR12" />
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>storage/*</exclude-pattern>
</ruleset>

Una vez que este archivo existe, normalmente puedes ejecutar phpcs sin repetir toda la definición del estándar en el comando.

Integración con editores y CI

La mayoría de editores pueden invocar phpcs directamente, lo que es útil para retroalimentación inmediata. En CI, phpcs funciona bien como un control de acceso porque sale con un estado distinto de cero cuando se encuentran violaciones. Eso facilita bloquear código sin formato antes de fusionar. La principal limitación a tener en cuenta es que phpcbf no puede corregir todas las violaciones que phpcs puede detectar. Esa es una de las razones por las que algunos equipos prefieren PHP-CS-Fixer para formateo y phpcs para informes.

Integración con editores y IDE: flujos de trabajo de formateo en tiempo real

La mejor configuración de formateo es aquella que los desarrolladores apenas notan porque ocurre automáticamente. Ahí es donde la integración con el editor importa. Si el formateo solo ocurre en CI, los desarrolladores se sienten interrumpidos. Si ocurre en el editor con la misma configuración que se usa en CI, el proceso se siente natural.

En PhpStorm, puedes configurar reglas de estilo de código integradas y también integrar herramientas externas como PHP-CS-Fixer o PHP_CodeSniffer. En VS Code, las extensiones comunes admiten phpcs, php-cs-fixer e incluso Prettier Plugin PHP. El detalle crítico es la consistencia: tu editor debe usar la misma herramienta, la misma versión y la misma configuración de proyecto que tus entornos de línea de comandos y CI.

Los conflictos suelen ocurrir cuando varias herramientas intentan formatear el mismo archivo al guardar. Por ejemplo, las configuraciones de estilo de PhpStorm pueden entrar en conflicto con PHP-CS-Fixer, o Prettier puede volver a formatear archivos después de que phpcbf se ejecuta. Si las acciones de guardado se sienten erráticas, elija un formateador principal por tipo de archivo y desactive el comportamiento de formateo al guardar que se superpone.

Buenas prácticas y convenciones de equipo

Un formateador funciona mejor cuando se convierte en parte de la cultura del equipo en lugar de una utilidad secundaria. Eso significa confirmar el archivo de configuración en el repositorio, bloquear las versiones de las herramientas y documentar el flujo de trabajo esperado en las notas de incorporación.

Para proyectos heredados, evite cambiar todo el código de la noche a la mañana a menos que lo planifique deliberadamente. Un enfoque más limpio es crear un commit dedicado de formateo, fusionarlo rápidamente y pedir al equipo que haga un rebase posteriormente. Otra opción es la adopción incremental, donde solo los archivos modificados deben ajustarse al formateador. Ambos enfoques son válidos. La elección correcta depende del tamaño del repositorio, la coordinación del equipo y la presión de las versiones.

Mantenga la revisión de código enfocada en la lógica. Si el formateador está haciendo su trabajo, los revisores no deberían perder tiempo pidiendo cambios de espacios en blanco. Esa es la verdadera ganancia de productividad.

Errores comunes y cómo evitarlos

La queja más grande sobre cualquier formateador de PHP es el churn de PR. Una rama de características pequeña puede de repente mostrar cientos de cambios solo de formato, lo que dificulta la revisión. La solución es disciplina de procesos: ejecute una pasada de formateo de referencia en su propio commit, y luego mantenga el trabajo de la característica separado.

La coincidencia de herramientas es otro problema común. Si su formateador y su linter discrepan, los desarrolladores pierden la confianza rápidamente. Alinee los estándares, reduzca la superposición cuando sea posible y pruebe el flujo de trabajo completo antes de hacer cumplir en CI.

El rendimiento también puede convertirse en un problema en repositorios grandes. Use caché, limite las ejecuciones a los archivos modificados en ganchos locales y reserve la validación de repositorio completo para CI o comprobaciones programadas. Si un arreglo automático parece cambiar el comportamiento, deténgase y verifique. El formateo no debe modificar la lógica, pero algunos fixers avanzados o arriesgados pueden generar efectos secundarios. Por eso las pruebas deben ejecutarse antes de la fusión.

Referencia rápida: comandos, fragmentos de configuración y plantillas de CI

Aquí están los comandos más útiles para mantener cerca en el trabajo diario:

Tarea	Comando
Ejecutar PHP-CS-Fixer	vendor/bin/php-cs-fixer fix
Previsualizar los cambios de PHP-CS-Fixer	vendor/bin/php-cs-fixer fix --dry-run --diff
Ejecutar phpcs con PSR-12	vendor/bin/phpcs --standard=PSR12 src tests
Corrección automática con phpcbf	vendor/bin/phpcbf --standard=PSR12 src tests

Una configuración práctica para muchos equipos es simple: usar PHP-CS-Fixer para formateo, opcionalmente usar phpcs para la aplicación y generación de informes, conectarlos a ganchos de pre-commit y CI, y mantener la configuración versionada en el repositorio.

Preguntas frecuentes

¿El formateo cambia el comportamiento del código?

Normalmente, no. Un formateador de PHP adecuado está diseñado para preservar el comportamiento mientras cambia el estilo. Aun así, algunos arreglos avanzados pueden ser más agresivos, por lo que es prudente ejecutar pruebas después de adoptar nuevas reglas.

¿Debo ejecutar un formateador en CI o localmente?

Ambos. El formateo local ofrece retroalimentación instantánea a los desarrolladores. CI ofrece una última barrera de consistencia para el equipo. Usarlos ambos evita sorpresas.

¿Cómo manejo repositorios con múltiples lenguajes?

Si su repositorio contiene PHP además de JavaScript, CSS, Markdown y JSON, un enfoque dividido funciona bien. Use un formateador dedicado de PHP para PHP y Prettier para activos de frontend, o adopte Prettier Plugin PHP si la consistencia entre lenguajes importa más que una personalización profunda específica de PHP.

¿Y los debates sobre el estilo de codificación?

Eso es exactamente para lo que sirve un formateador. Decida una vez, configure la herramienta y continúe con la revisión de la arquitectura, la corrección y la mantenibilidad.

Recursos y referencias adicionales

La documentación oficial sigue siendo el mejor lugar para verificar el soporte de reglas, detalles de instalación y la compatibilidad actual de la sintaxis. Comience con PHP-CS-Fixer en GitHub, PHP_CodeSniffer en GitHub, la documentación de PhpStorm en jetbrains.com y Prettier en prettier.io.

Si está implementando un formateador para un equipo hoy, el siguiente paso más efectivo es directo. Elija una herramienta, confirme una configuración del proyecto, ejecútelo en una pequeña parte del código y conéctelo a su editor y CI. Una vez que eso funciona sin problemas, expanda el alcance. Un formateador de PHP confiable no solo limpia el código, también limpia todo el proceso de desarrollo.