Análisis estático en PHP heredado: plan seguro de modernización

Introducir análisis estático en PHP heredado no consiste en activar el nivel más estricto de una herramienta y corregir miles de avisos. En una aplicación con reglas de negocio dispersas, dependencias antiguas y pocas pruebas, ese enfoque mezcla defectos potencialmente graves con deuda histórica, frena al equipo y puede inducir cambios inseguros.

El objetivo inicial es distinto: hacer que cada modificación nueva sea más verificable, reducir la incertidumbre en los flujos importantes y disponer de una ruta explícita para tratar la deuda existente. El análisis estático aporta información estructural sobre el código; la modernización requiere además decisiones de producto, pruebas y controles de entrega.

Por qué activar todas las reglas de golpe suele paralizar el mantenimiento

Un proyecto legado puede acumular tipos implícitos, valores nulos no documentados, métodos con demasiadas responsabilidades, acceso directo a variables globales, código no alcanzable y contratos ambiguos entre capas. Si se analiza todo el repositorio con reglas estrictas desde el primer día, el resultado suele ser una lista demasiado extensa para priorizar.

El problema no es sólo el volumen. Cada aviso exige contexto: una llamada aparentemente incorrecta puede estar protegida por una condición externa, una dependencia puede usar anotaciones incompletas o una convención local puede no estar representada en el código. Corregir sin comprender ese contexto puede cambiar un comportamiento de negocio que nadie había documentado.

También conviene separar dos objetivos que a menudo se confunden:

• Visibilidad: conocer riesgos y zonas con contratos inciertos.
• Control de cambios: impedir que una modificación introduzca nuevos problemas detectables.
• Reducción de deuda: eliminar incidencias históricas de forma priorizada.

El segundo objetivo es el mejor punto de partida. Permite mejorar la calidad de entrega sin convertir la corrección masiva en un requisito previo para seguir desarrollando producto.

Qué detecta el análisis estático y qué controles no sustituye

Un analizador puede inferir tipos, seguir llamadas, detectar argumentos incompatibles, retornos imposibles, propiedades no definidas, variables que pueden ser nulas, ramas inalcanzables y discrepancias entre una interfaz y su implementación. También ayuda a localizar dependencias acopladas, APIs usadas de forma inconsistente y límites de arquitectura vulnerados cuando se definen reglas para ello.

Estas señales son especialmente valiosas en refactorizaciones. Por ejemplo, cambiar un método para que devuelva Customer|null permite encontrar consumidores que asumen siempre una instancia. El aviso no demuestra que exista un error en producción, pero obliga a decidir qué debe ocurrir cuando no hay cliente.

Sin embargo, el análisis no valida por sí solo una regla como que un pedido sólo pueda cancelarse antes de facturarse, que un descuento se calcule conforme a una política comercial o que una integración externa responda dentro de un plazo aceptable. Tampoco observa permisos reales, migraciones de datos, concurrencia, rendimiento ni configuraciones de producción.

Una refactorización segura combina tres perspectivas:

• Análisis estático para comprobar contratos y recorridos de código.
• Pruebas automatizadas para preservar comportamientos conocidos, empezando por los flujos críticos.
• Revisión funcional y observación para validar reglas de negocio, efectos externos y comportamiento tras el despliegue.

Preparar el piloto antes de medir incidencias

El primer alcance debe ser un módulo de negocio acotado, con cambios frecuentes o riesgo relevante, pero no el núcleo más opaco de toda la aplicación. Un piloto útil tiene responsables identificables y permite conocer si las reglas generan hallazgos comprensibles.

Antes de ejecutar el análisis, construya un inventario breve:

1. Rutas críticas: autenticación, pagos, pedidos, facturación, datos personales u otras operaciones cuyo fallo tenga impacto alto.
2. Entradas y salidas: controladores, comandos, consumidores de colas, APIs, archivos importados y trabajos programados.
3. Dependencias: versión de PHP, paquetes abandonados, extensiones, código generado y librerías sin información de tipos.
4. Convenciones actuales: uso de clases de valor, excepciones, colecciones, nulos, arrays asociativos y acceso a datos.
5. Pruebas disponibles: qué escenarios cubren, qué datos preparan y cuáles son sus límites de confianza.

Este inventario evita interpretar cada aviso de manera aislada. También permite decidir dónde tiene sentido añadir tipos nativos y dónde conviene mantener adaptadores alrededor de una dependencia antigua para no propagar su ambigüedad por toda la aplicación.

Crear una línea base sin convertirla en una amnistía permanente

La línea base registra las incidencias ya existentes para que el equipo pueda exigir un estándar superior en el código nuevo o modificado. Es una herramienta de transición, no una declaración de que la deuda es aceptable.

Genérela tras revisar una muestra representativa de hallazgos. Si el resultado contiene errores de configuración, rutas que no deberían analizarse o código de terceros incluido por accidente, corríjalo primero. Una línea base inflada por ruido pierde valor desde el inicio.

Para que sea útil, asóciela a reglas operativas:

• No se añaden nuevas entradas a la línea base sin una justificación revisable.
• Una incidencia corregida se elimina de la línea base en el mismo cambio.
• Las entradas se revisan al intervenir el archivo o módulo afectado.
• Las excepciones tienen propietario, motivo técnico y fecha o condición de revisión.

Es preferible registrar una supresión muy localizada con explicación que ocultar una categoría completa de errores. Si un aviso no puede resolverse porque una biblioteca externa no expresa sus contratos, encapsule esa biblioteca en un adaptador tipado y limite la excepción a ese borde.

Clasificar hallazgos por riesgo y coste de decisión

No todos los diagnósticos merecen bloquear una entrega. La clasificación debe reflejar el impacto potencial y el grado de certeza, no sólo la severidad que asigne una herramienta.

Prioridad alta: contratos y datos críticos

Trate primero retornos incompatibles, argumentos mal tipados en operaciones de negocio, accesos posibles a nulos, valores no validados en límites externos y violaciones de contratos entre módulos. Suelen revelar defectos que una prueba insuficiente puede no recorrer.

Prioridad media: incertidumbre que amplía el alcance

Los arrays sin forma conocida, valores mixtos que atraviesan varias capas y métodos que devuelven tipos demasiado amplios no siempre causan un fallo inmediato. Aun así, elevan el coste de cada cambio. Conviene resolverlos al tocar el flujo, definiendo objetos de transferencia, clases de valor o contratos explícitos cuando tengan sentido.

Prioridad baja: limpieza sin impacto demostrado

Estilo, código redundante o convenciones internas pueden mejorar la legibilidad, pero no deberían competir con riesgos de dominio ni con entregas urgentes. Agrúpelos en tareas separadas o aplique reglas automáticas sólo cuando su modificación sea mecánica y verificable.

Orden de intervención: impedir deuda nueva y proteger flujos activos

Una secuencia práctica comienza por ejecutar el análisis en integración continua sobre las modificaciones propuestas. El criterio de bloqueo inicial puede ser simple: no introducir errores nuevos fuera de la línea base y no empeorar el nivel de un archivo modificado.

Después, endurezca reglas por directorio o módulo. Es habitual empezar por código de dominio nuevo, servicios de aplicación y adaptadores recientes, mientras se mantienen criterios más tolerantes en capas históricas de infraestructura. Esta división no es una excusa para abandonar el legado: hace visible dónde está el límite y permite desplazarlo gradualmente.

En cada cambio activo, priorice un alcance pequeño:

1. Añada pruebas de caracterización para el comportamiento que necesita preservar.
2. Declare el contrato de entrada y salida más relevante.
3. Corrija los avisos que afecten a ese recorrido.
4. Refactorice en pasos cortos y revise diferencias funcionales.
5. Active reglas más estrictas cuando el módulo pueda sostenerlas.

Los tipos y anotaciones deben describir conocimiento real. Declarar un tipo no nulo sólo para silenciar un aviso traslada el riesgo al siguiente consumidor. Si un valor puede faltar por diseño, represéntelo como tal y obligue al código llamador a decidir cómo manejarlo.

Integrar controles en la entrega continua sin bloquear por ruido

El resultado del análisis debe ser legible para quien abre un cambio. Publique los errores nuevos, el archivo afectado, la regla y una indicación de por qué importa. Evite informes extensos sin responsable ni relación con la modificación realizada.

Defina criterios proporcionados: los defectos de contrato en un flujo crítico pueden bloquear; una mejora cosmética puede convertirse en seguimiento; una alerta incierta de una dependencia debe derivar en un adaptador, una configuración documentada o una excepción temporal. La revisión de código decide si la corrección respeta la intención de negocio; el analizador no reemplaza esa decisión.

Mida el avance con indicadores que orienten decisiones: incidencias relevantes abiertas por módulo, entradas de línea base eliminadas, porcentaje de cambios analizados con reglas exigentes, número de contratos ambiguos en rutas críticas y proporción de refactorizaciones cubiertas por pruebas de caracterización. El objetivo no es llegar a cero avisos globales, sino reducir el alcance incierto de los cambios.

Antipatrones que confunden limpieza con modernización

• Suprimir avisos sin motivo: elimina información sin reducir el riesgo que la originó.
• Perseguir cero hallazgos: puede dedicar capacidad a detalles irrelevantes mientras siguen inseguros los procesos importantes.
• Corregir todo archivo cercano: aumenta el tamaño del cambio y dificulta revisar regresiones.
• Tipar datos desconocidos como si fueran fiables: oculta incertidumbre en lugar de modelarla.
• Bloquear toda entrega por reglas nuevas: genera rechazo y empuja al equipo a buscar excepciones permanentes.

Lista de comprobación para iniciar el piloto

• Elegir un módulo con dueño técnico, relevancia de negocio y alcance acotado.
• Identificar sus entradas, salidas, dependencias y escenarios críticos.
• Ejecutar el análisis, eliminar errores de configuración y revisar una muestra de resultados.
• Crear una línea base limitada a deuda existente y definir quién puede modificarla.
• Bloquear incidencias nuevas de alto riesgo en cambios del piloto.
• Añadir pruebas de caracterización antes de refactorizar recorridos sensibles.
• Revisar semanalmente hallazgos repetidos, excepciones y reglas que generan ruido.
• Endurecer el estándar sólo cuando los resultados sean comprensibles y accionables.

Con este enfoque, el análisis estático deja de ser un informe de defectos heredados y se convierte en un mecanismo de control: cada modificación aporta contratos más claros, menor incertidumbre y una base más segura para modernizar PHP de forma progresiva.