wp-phpstan

Descripción general de la skill wp-phpstan

wp-phpstan es la skill que debes usar cuando necesitas que PHPStan funcione bien en un código base de WordPress, no solo que “se ejecute más o menos”. Está pensada para desarrolladores de plugins, temas y sitios que quieren un análisis estático más limpio, menos falsos positivos y una vía práctica para el código heredado que ya arrastra problemas.

La tarea principal es de configuración y corrección: enlazar phpstan.neon, gestionar baselines, cargar stubs de WordPress y añadir anotaciones de tipo compatibles con WordPress allí donde PHPStan no puede inferir el comportamiento en tiempo de ejecución.

Para qué es mejor wp-phpstan

Usa la skill wp-phpstan cuando necesites:

• configurar o actualizar PHPStan en un repositorio de WordPress
• reducir errores causados por símbolos faltantes del core de WordPress
• gestionar phpstan-baseline.neon sin ocultar regresiones nuevas
• corregir patrones dinámicos de WordPress como hooks, peticiones REST y resultados de consultas
• trabajar con clases opcionales de plugins de terceros como WooCommerce o ACF

En qué se diferencia esta skill

Un prompt genérico para PHPStan suele pasar por alto restricciones propias de WordPress: clases cargadas en tiempo de ejecución, callbacks de hooks, dependencias de plugins y entornos de análisis que no coinciden con el sitio en producción. wp-phpstan es útil porque se centra primero en esos casos límite, sobre todo en la carga de stubs y los ignores acotados.

Cuándo no usarla

Si solo necesitas una explicación rápida y puntual de un comando de PHPStan, esta skill quizá sea más de lo que necesitas. Es más valiosa cuando la calidad del análisis importa lo suficiente como para que las decisiones de configuración, la política de baseline y las pistas de tipos cambien el resultado.

Cómo usar la skill wp-phpstan

Instala y verifica la skill

Para wp-phpstan install, añade la skill desde el repositorio de skills del agente de WordPress:

npx skills add WordPress/agent-skills --skill wp-phpstan

Después de instalarla, lee primero SKILL.md y luego las referencias de apoyo y el script de inspección. El repositorio está organizado para responder las preguntas que más influyen en la adopción: qué ve PHPStan, qué ignora y qué conviene tipar en lugar de suprimir.

Dale a la skill los datos correctos

La skill wp-phpstan funciona mejor cuando aportas contexto del proyecto antes de pedir correcciones. Empieza con:

• la salida de wp-project-triage
• si se pueden modificar las dependencias de desarrollo de Composer
• si está permitido actualizar la baseline
• los errores concretos de PHPStan o el archivo de configuración que quieres cambiar

Un prompt flojo: “Arregla PHPStan en mi plugin de WordPress.”

Un prompt más sólido: “Usa wp-phpstan para inspeccionar la configuración actual de PHPStan de mi plugin, confirmar si szepeviktor/phpstan-wordpress está cargado y proponer el cambio mínimo de configuración que corrija las funciones desconocidas de WordPress sin ignores amplios. Los cambios en la baseline solo están permitidos para errores heredados ya existentes.”

Flujo de trabajo y archivos recomendados

Para un uso práctico de wp-phpstan, sigue la ruta de decisión del propio repositorio:

1. Inspecciona la configuración con scripts/phpstan_inspect.mjs
2. Revisa los archivos principales de configuración y baseline
3. Consulta references/configuration.md
4. Lee references/third-party-classes.md
5. Usa references/wordpress-annotations.md cuando el problema sea de inferencia de tipos, no de configuración

Si quieres ir más rápido al resultado correcto, revisa antes estos archivos:

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Forma práctica de formular el prompt

Los buenos prompts le dicen a la skill qué está fijo, qué es flexible y qué salida esperas. Por ejemplo:

• “Audita mi phpstan.neon de un plugin de WordPress y dime si debo añadir stubs, ajustar ignoreErrors o actualizar la baseline.”
• “Reescribe esta anotación de un controlador REST para que PHPStan entienda la forma de la petición.”
• “Mi entorno de análisis no incluye WooCommerce; propone una estrategia acotada de stubs/ignores para estas clases faltantes.”

Ese nivel de detalle ayuda a wp-phpstan a elegir entre cambios de configuración, anotaciones o cambios de dependencias.

Preguntas frecuentes sobre la skill wp-phpstan

¿wp-phpstan es solo para plugins de WordPress?

No. La skill wp-phpstan también encaja en temas y sitios de WordPress con código personalizado. Es especialmente útil en cualquier lugar donde PHPStan necesite ayuda para entender el comportamiento en tiempo de ejecución de WordPress.

¿Necesito tener Composer y PHPStan ya instalados?

Sí, esta skill asume un flujo de trabajo de PHPStan basado en Composer. Si tu repositorio no usa Composer o si PHPStan no forma parte de la cadena de herramientas, la skill no es una buena opción.

¿Es mejor que escribir un prompt personalizado?

Normalmente sí, si te importan las decisiones de configuración repetibles. Un prompt personalizado puede resolver un error puntual, pero wp-phpstan te ofrece un mejor flujo para baselines, stubs y tipado específico de WordPress.

¿Cuándo debo evitar ignores amplios?

Evita los ignores amplios cuando la clase o la función sí existen, pero faltan por un stub ausente, un problema de autoload o un desajuste del entorno de análisis. Usa ignores acotados solo después de verificar que la ruta de dependencia es real y no se puede corregir de forma limpia.

Cómo mejorar la skill wp-phpstan

Dale el modo real de fallo de PHPStan

Los mejores resultados con wp-phpstan llegan cuando identificas el tipo de fallo antes de pedir la corrección:

• funciones desconocidas del core de WordPress → stubs o configuración
• ruido heredado → flujo de baseline
• datos dinámicos de petición → @phpstan-param o alias de tipo reutilizables
• APIs opcionales de plugins → stubs acotados o ignores concretos

Si solo pegas una lista de errores, la skill puede optimizar el síntoma en lugar de la causa.

Comparte el límite del análisis

Dile a la skill qué puede cambiar. Los resultados mejoran cuando especificas:

• ¿puede editar composer.json?
• ¿puede añadir dependencias de desarrollo?
• ¿puede cambiar phpstan.neon?
• ¿puede regenerar la baseline?

Esos permisos determinan si wp-phpstan debe priorizar correcciones de código, de configuración o de dependencias.

Prioriza entradas concretas frente a objetivos genéricos

Una entrada más sólida produce una salida mejor. Por ejemplo, incluye:

• el nivel actual de PHPStan
• los directorios que analizas
• si WordPress core está presente en CI
• el plugin o la clase exacta que provoca errores de símbolos ausentes

Esto ayuda a la skill wp-phpstan a recomendar la ruta correcta de instalación y uso para trabajo de Backend Development, en lugar de limitarse a una lista genérica de comprobaciones de PHPStan.

Itera de la configuración a las anotaciones

Una buena wp-phpstan guide suele seguir este orden:

1. verificar stubs y descubrimiento
2. acotar excludes e ignores
3. anotar tipos dinámicos específicos de WordPress
4. actualizar la baseline solo para la deuda heredada aceptada

Ese orden mantiene el análisis lo bastante estricto como para detectar problemas nuevos, a la vez que reduce los falsos positivos allí donde el modelo dinámico de WordPress bloquea la inferencia.