PHPStan y Psalm para analisis estatico

El motor de PHP es debilmente tipado en tiempo de compilacion. Aunque las versiones modernas permiten declarar tipos en firmas y propiedades, muchos errores solo aparecen al ejecutar el codigo. En proyectos grandes ese descubrimiento tardio es costoso, sobre todo cuando el bug viaja hasta produccion.

El analisis estatico recorre el codigo fuente sin ejecutarlo, construye un modelo de tipos y detecta usos sospechosos. Las dos herramientas de referencia del ecosistema PHP son PHPStan y Psalm. Ambas cubren casi el mismo terreno con matices propios y se pueden integrar con la misma facilidad.

Por que analisis estatico

Un analizador estatico encuentra clases de errores que los tests unitarios no siempre detectan, al menos no hasta que se escriben pruebas para cada rama. Entre ellos destacan:

• 1 - Llamadas a metodos inexistentes por cambios de API o errores tipograficos.
• 2 - Propiedades nunca asignadas antes de ser leidas.
• 3 - Tipos incompatibles pasados a parametros de funciones o retornados.
• 4 - Ramas muertas y condiciones siempre verdaderas o falsas.
• 5 - Dependencias no declaradas en el composer.json.

Detectar estos problemas mientras se escribe el codigo acelera el desarrollo. La herramienta se ejecuta en el editor mientras codificas y en el CI antes de fusionar el cambio.

flowchart LR
    A[Codigo fuente] --> B[Analizador estatico]
    B --> C[Modelo de tipos]
    C --> D[Reglas y niveles]
    D --> E[Informe de errores]
    E --> F[Integracion con editor]
    E --> G[Integracion con CI]

Instalar PHPStan

PHPStan se instala como dependencia de desarrollo via Composer. Basta con anadirlo al proyecto y configurar un archivo phpstan.neon en la raiz.

composer require --dev phpstan/phpstan

El archivo de configuracion minimo indica el nivel de analisis y las rutas a inspeccionar.

parameters:
    level: 8
    paths:
        - src
        - tests

PHPStan define diez niveles del 0 al 9, siendo 0 el mas permisivo y 9 el mas estricto. Un proyecto greenfield deberia empezar directamente en 8 o 9. Un proyecto heredado empieza en el nivel maximo que pasa y sube progresivamente.

El comando de ejecucion es breve:

vendor/bin/phpstan analyse

Interpretar los errores

Un error tipico de PHPStan indica el archivo, la linea y el mensaje concreto. Algunos ejemplos habituales son:

Method App\Domain\Usuario::email() has no return type specified.
Parameter #1 $email of method App\Domain\Usuario::__construct() expects string, int given.
Property App\Domain\Pedido::$estado type mapping mismatch: property can contain null but no null default or nullable type.

Cada mensaje apunta a una violacion concreta del contrato de tipos. La mayoria se resuelven anadiendo el tipo correcto o cambiando el valor pasado. Algunos requieren refactor, y unos pocos deben marcarse como falsos positivos legitimos, con un comentario @phpstan-ignore-line justificado.

Evita silenciar errores sin entender su causa. Un @phpstan-ignore indocumentado acaba siendo una deuda tecnica invisible.

Baseline y proyectos heredados

Para proyectos antiguos que generan cientos o miles de errores al activar analisis estatico, existe la tecnica del baseline. Se captura el estado actual de errores en un archivo y PHPStan deja de reportarlos hasta que vuelven a aparecer en nuevas lineas.

vendor/bin/phpstan analyse --generate-baseline

El baseline se incluye en el repositorio y se revisa periodicamente. Los desarrolladores pueden concentrarse en que el codigo nuevo cumpla el nivel elegido, mientras el codigo antiguo se sanea a medida que se toca.

Instalar Psalm

Psalm es la alternativa con mayor enfasis en genericos e inferencia. Se instala tambien via Composer.

composer require --dev vimeo/psalm

La configuracion vive en psalm.xml en la raiz del proyecto. Se puede generar con el comando inicial.

vendor/bin/psalm --init

El archivo resultante parte de un nivel inicial razonable y puedes ajustar las rutas y las reglas. El comando de ejecucion rutinario es directo.

vendor/bin/psalm

Psalm distingue entre errores, avisos e informaciones, y permite activar o desactivar reglas especificas. Su salida es muy detallada y suele acompanarse de sugerencias de correccion.

Genericos con PHPStan y Psalm

PHP no tiene genericos nativos, pero PHPStan y Psalm entienden anotaciones estandarizadas en docblock para expresarlos. Esta doble capa permite escribir bibliotecas con tipos precisos sin romper compatibilidad con PHP.

<?php

/**
 * @template T
 */
final class Coleccion
{
    /** @var list<T> */
    private array $items = [];

    /**
     * @param T $item
     */
    public function agregar(mixed $item): void
    {
        $this->items[] = $item;
    }

    /**
     * @return list<T>
     */
    public function todos(): array
    {
        return $this->items;
    }
}

/** @var Coleccion<string> $c */
$c = new Coleccion();
$c->agregar("alfa");

Con estas anotaciones, el analizador sabe que $c->todos() devuelve list<string> y marca como error cualquier uso incompatible.

Los arrays de forma conocida se anotan con array{id: int, nombre: string}, lo que convierte un array asociativo en casi un record con comprobacion de campos.

Rector: refactor automatico

Un complemento habitual del analisis estatico es Rector, una herramienta que aplica refactors automaticos basados en reglas. Puede migrar proyectos entre versiones de PHP, modernizar sintaxis y eliminar codigo deprecado.

composer require --dev rector/rector

Con una configuracion minima en rector.php, la herramienta aplica o sugiere cambios.

<?php

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return static function (RectorConfig $config): void {
    $config->paths([__DIR__ . "/src"]);
    $config->sets([LevelSetList::UP_TO_PHP_84]);
};

Rector no sustituye al desarrollador, pero automatiza la parte mecanica de migraciones masivas, dejando para humanos solo las decisiones con matiz.

Integracion con el editor

PhpStorm integra ambos analizadores de forma nativa. En la configuracion del IDE se indica la ruta al ejecutable y PhpStorm subraya los errores en tiempo real mientras escribes. Los mensajes aparecen junto al codigo con el mismo nivel de detalle que en la linea de comandos.

Esta integracion cambia la dinamica: dejas de pensar en el analisis estatico como un paso separado y pasa a ser una segunda capa de correccion instantanea junto al resaltado del lenguaje.

Integracion continua

El analisis estatico se incorpora al pipeline de CI para que un pull request no se pueda mergear si introduce errores. En GitHub Actions, por ejemplo, un paso anade:

En GitLab, Bitbucket o cualquier otro motor el patron es identico: instalar dependencias con Composer y ejecutar el analizador. La tecnica conocida como fail-fast elimina ciclos donde un error escala hasta produccion.

Establece un contrato claro en el equipo: el nivel de PHPStan o Psalm acordado es no negociable en codigo nuevo. Cada excepcion se documenta en el PR correspondiente.

Elegir entre PHPStan y Psalm

Las dos herramientas son excelentes y cubren necesidades equivalentes. PHPStan tiene una comunidad algo mayor en proyectos Laravel y Symfony, con extensiones especificas para ambos frameworks. Psalm es la eleccion habitual en proyectos donde se prioriza la inferencia mas agresiva y el detalle en los mensajes.

Muchos proyectos conviven con las dos durante una temporada, especialmente al adoptar analisis estatico por primera vez. No hay conflicto en ejecutar ambas, aunque con el tiempo suele elegirse una como herramienta principal.

Integrar PHPStan o Psalm en el dia a dia reduce el volumen de bugs que llegan a produccion, acorta los ciclos de revision de codigo y eleva la confianza al refactorizar. En un curso corporativo la practica deberia consolidarse en las primeras semanas para que el resto del proyecto se desarrolle sobre una red de seguridad solida.