PHPStan obtuvo un lanzamiento clave a principios de noviembre de 2021 con nuevas funciones, reglas adicionales y muchas optimizaciones de rendimiento. Significa que el analizador estático de PHP líder ahora se considera estable y viene con la promesa de compatibilidad con versiones anteriores para futuras actualizaciones.
Como se trata de un gran problema, PHPStan 1.0 también realiza algunos cambios importantes que pueden afectar los escaneos existentes. Estos incluyen reglas adicionales y algunos parámetros de configuración reemplazados o eliminados.
El nuevo nivel 9
CONTENIDOS DE LA PAGINA
PHPStan escanea su fuente PHP en busca de problemas potenciales sin realmente ejecutar el código. Además de las pruebas unitarias y de un extremo a otro, esto le brinda visibilidad de la calidad de su código al exponer los problemas antes de que los usuarios los encuentren.
Los niveles de PHPStan se utilizan para configurar la gravedad del analizador. La serie de versiones v0.x ofrecía ocho niveles, siendo 0 el más relajado y 8 el más estricto. Si bien es preferible utilizar el nivel más estricto posible para obtener la mejor cobertura, los niveles menos estrictos pueden ayudarlo a introducir PHPStan en una base de código imperfecta.
PHPStan 1.0 agrega el nivel 9 como una nueva opción. Incluye todas las reglas desde el nivel 8 en adelante, más una verificación adicional: estricta mixed
comparaciones de tipos.
los mixed
type llegó a PHP 8.0 como una forma de escribir explícitamente «cualquier» valor. Igual que mixed
es esencialmente equivalente a un valor sin tipo, no es seguro adivinar qué mixed
-type es similar al valor.
El noveno nivel de PHPStan lo hará cumplir estrictamente al informar un error si intenta utilizar activamente un mixed
valor en su código. No se permite acceder a una propiedad o llamar a un método, ya que no es posible saber si existirán. Solo puedes pasar valores a través de otros mixed
-type da pistas cuando esta regla está activa.
Para activar el nuevo comportamiento, deberá cambiar level: 8
para level: 9
en tus phpstan.neon
archivo de configuración. PHPStan también admite level: max
como un alias para el nivel más alto. Si ya está usando max
, obtendrá el nivel 9 automáticamente cuando actualice a PHPStan 1.0.
Mejor conocimiento en los bloques Try-Catch-Finalmente
PHPStan ahora tiene una mejor inferencia de tipos y conocimiento de variables para los bloques try-catch-finalmente. Usará el @throws
docblock para verificar los tipos de excepción lanzados por cada función en su código base. Este conocimiento se utiliza para informar las verificaciones de disponibilidad de variables dentro de los bloques try-catch.
Aquí hay un ejemplo que demuestra por qué esto es importante:
/** * @throws DemoException */ function first() { throw DemoException(); } /** * @throws OtherException */ function second() { throw OtherException(); } try { $first = first(); $second = second(); } catch (DemoException $ex) { error_log($second); } catch (Exception $ex) { error_log("General exception"); }
El primero catch
acceso al blog $second
pero esto no existirá cuando DemoException
Está capturado. PHPStan v1.0 utiliza el @throws
declaración para darse cuenta de ello para que esté informado cuando su catch
los bloques se refieren a variables posiblemente indefinidas. Funciones sin @throws
las anotaciones generalmente se comportarán como antes.
Tras este cambio, el opcional polluteCatchScopeWithTryAssignments
El parámetro ha sido eliminado. Esto le permitió acceder a las variables establecidas en un try
bloque dentro de lo siguiente catch
; ya no es necesario ya que PHPStan ahora puede determinar qué variables están disponibles.
Detección de código no utilizado
PHPStan ha mejorado en la búsqueda y notificación de algunas formas de código no utilizado en su proyecto. Resaltará las propiedades, métodos y constantes de la clase privada a las que nunca se llama ni se accede a ellas.
Su presencia es casi siempre involuntaria. Si desea mantener el código muerto por más tiempo, puede intentar comentarlo o agregar el @phpstan-ignore-next-line
comentario para eludir el cheque.
Mejoras en los valores recordados
v1.0 mejora la consistencia de la memoria PHPStan para los valores de retorno de funciones. Es más hábil para averiguar cuándo se llama a una función por segunda vez, lo que ofrece una mejor anticipación de valores de retorno idénticos.
Esto conduce a una mejor detección de códigos muertos cuando una condición se repite varias veces. PHPStan le advertirá cuando un bloque se vuelva redundante porque la ejecución finalizó desde una rama anterior con la misma condición:
if ($demo -> isActive()) { return; } if ($demo -> isActive()) { recordDemoActivity(); }
El segundo bloque nunca se ejecutará ya que el primero siempre termina. Sin embargo, hay una suposición en juego: isActive()
siempre debe devolver el mismo valor por la duración de $demo
. En términos más concretos, isActive()
debe ser una función pura donde las entradas repetidas siempre producen una salida idéntica.
PHPStan asume que las funciones son puras por defecto. En los casos en que no lo estén, puede agregar el @phpstan-impure
anotación en un docblock encima de la definición de la función. Esto deshabilitará la memoria del valor de retorno para esa función. Debería usarlo en el ejemplo anterior si isActive()
podría devolver un valor diferente en cada llamada, lo que significa que la primera comprobación podría ser igual a false
y permita que se ejecute la segunda rama.
/** @phpstan-impure */ public function isActive() : bool { return (date("Y") === "2021"); }
Otras mejoras de reglas
Se han agregado varias reglas nuevas a los niveles existentes 1 a 6. Estas incluyen verificaciones para invalidar constantes y propiedades, tratando de extender un final
clase y detección siempre verdadera y siempre falsa while
condiciones del ciclo.
Los tipos ahora se comprueban de forma recursiva en busca de pistas faltantes. Esto significa que las definiciones de PHPDoc como array<array>
no se aceptarán porque carecen de una definición de tipo interna. También deberá escribir los valores esperados de los elementos de la matriz de segundo nivel, como array<array<string>>
.
Además de verificar el contenido fuente, PHPStan 1.0 examina la validez general de .php
archivos también. El nivel 0 obtiene una verificación de los espacios en blanco y la lista de materiales de los archivos iniciales y finales, como los caracteres extraviados antes o después de la <?php ... ?>
Un par de etiquetas puede causar una salida inesperada en tiempo de ejecución.
Rendimiento y estabilidad
El rendimiento se ha mejorado en varias áreas optimizando operaciones específicas y solucionando algunas pérdidas de memoria. Estos deberían contribuir a escaneos más rápidos y confiables de bases de código más grandes.
Dado que la v1.0 se considera una versión estable formal, se ofrece la garantía de que las futuras versiones menores (1.1, 1.2, 1.3, etc.) serán compatibles con versiones anteriores. Si bien el cambio de v0.xa v1.0 puede requerir algunos cambios de configuración, tendrá una ruta de migración más sencilla en el futuro.
Los desarrolladores de extensiones de PHPStan y conjuntos de reglas personalizadas también se benefician de tener una base de código más estable que es menos probable que cambie. La documentación para desarrolladores también se ha ampliado para incluir una cobertura más accesible de la creación de reglas personalizadas. Debería ser más fácil comenzar a implementar las reglas de su equipo en su análisis PHPStan.
Si bien esto es un buen augurio para el soporte futuro, tanto los usuarios como los desarrolladores de extensiones enfrentan cambios importantes en el cambio a la v1.0. Varios parámetros de configuración de escaneo han sido renombrados o cambiados, con bootstrap
volverse bootstrapFiles
Y excludes_analyse
reemplazadas con excludePaths
.
Internamente, la API de extensiones se ha revisado ampliamente, por lo que se han cambiado o eliminado muchas clases y métodos. La lista completa de cambios que no son compatibles con versiones anteriores está disponible en el registro de cambios v1.0.
Resumen
PHPStan v1.0 madura el proyecto optimizando el rendimiento, agregando nuevas reglas y corrigiendo algunas irregularidades de detección. La evolución de PHPStan en los últimos años ha contribuido al cambio más grande de la comunidad PHP hacia la adopción de conceptos de lenguaje escrito. La adición de características como propiedades escritas y tipos de unión dio como resultado un lenguaje que podría admitir una inspección externa avanzada, así como una introspección interna detallada a través de la reflexión.
La promoción a una versión siempre estable debería ayudar a fomentar una mayor adopción de PHPStan en toda la comunidad. La migración a la nueva versión debería ser lo suficientemente simple para proyectos modernos que ya usan una capa de reglas PHPStan estricta.
Puede actualizar a PHPStan v1.0 hoy ejecutando composer require phpstan/phpstan
en sus proyectos Se recomienda que primero lea las notas de la versión para identificar los cambios sustanciales que deben abordarse. Tener reglas adicionales en cualquier nivel existente puede hacer que su base de código comience a fallar en las pruebas incluso si ha pasado PHPStan v0.x. Puede deshabilitar temporalmente nuevas reglas agregándolas a su línea de base para que se excluyan de los resultados del análisis.