Plantillas verificadas con PHPStan y un AGENTS.md generado
Un bloque Blockstudio consta de dos archivos que deben coincidir. El block.json declara los campos y la plantilla los lee como $a['id']. Nada en tiempo de ejecución impide que la plantilla lea una clave que se haya renombrado, que nunca se haya declarado o que esté mal escrita. Simplemente muestra una cadena vacía, y el error sale a la luz cuando alguien ve un encabezado en blanco en una página publicada. Lo mismo ocurre con el escape de salida: un echo sin escapar funciona perfectamente hasta que un valor de campo contiene marcado.
El paquete blockstudio/phpstan traslada ambos problemas al análisis estático. Lee sus archivos block.json, obtiene sus tipos $a y señala las lecturas de plantilla que no coinciden. Sus preajustes opcionales añaden reglas para la estructura del tema, el escape y comprobaciones de JavaScript y Tailwind. El paquete incluye dos herramientas complementarias: un hook de precommit administrado que ejecuta el análisis y un generador que crea un AGENTS.md con información sobre el proyecto para los agentes de programación.
Esta guía crea un tema pequeño, rompe una de sus plantillas a propósito, examina el resultado del análisis, corrige el problema y, después, configura la puerta de control de commits y el contrato para agentes.
Configurar el tema
Empiece con una carpeta de tema que tenga un encabezado style.css, un composer.json y un bloque:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Instale el paquete como dependencia de desarrollo:
composer require --dev blockstudio/phpstan
Instala PHPStan y los stubs de WordPress de szepeviktor/phpstan-wordpress, e instala tres ejecutables en vendor/bin: blockstudio-phpstan, blockstudio-githooks y blockstudio-agents.
Después, indique al análisis qué debe ejecutar. Los valores predeterminados de todo el proyecto se encuentran en el objeto phpstan de blockstudio.json, para que las ejecuciones interactivas, CI y el hook de commits usen la misma configuración:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme es el más estricto de los tres preajustes estáticos. La tabla más abajo explica qué añade cada uno. excludePaths excluye los propios archivos de Composer del análisis Blockstudio y del análisis de PHP.
Romper una plantilla a propósito
El bloque principal declara un único campo:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
La plantilla lee correctamente ese campo, pero luego lee un subtitle que el bloque nunca declaró y lo muestra sin escapar:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
En el editor y en el frontend, esto muestra un párrafo vacío y ningún error. En su lugar, ejecute el análisis:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
Line blockstudio/hero/index.php
------ -------------------------------------------------------------------
2 Variable $a might not be defined.
🪪 variable.undefined
3 Dynamic Blockstudio attributes must be escaped before output.
🪪 blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
🪪 blockstudio.field
3 Offset 'subtitle' does not exist on array{heading: string}.
🪪 offsetAccess.notFound
3 Parameter #1 (mixed) of echo cannot be converted to string.
🪪 echo.nonString
3 Variable $a might not be defined.
🪪 variable.undefined
------ -------------------------------------------------------------------
[ERROR] Found 6 errors
El comando termina con 1. Lea los diagnósticos, del más específico al más general:
blockstudio.fieldes la regla de plantilla. Encontró elblock.jsonjunto a la plantilla, resolvió sus campos y determinó quesubtitleno es uno de ellos.offsetAccess.notFoundes el propio PHPStan y llega a la misma conclusión, porque la extensión asigna a$ala estructura concretaarray{heading: string}derivada deblock.json. Cada tipo de campo se corresponde con un tipo de PHP:textes unstring,togglees unbooly un repetidor es una matriz de estructuras de fila.blockstudio.output.unescapedprocede de la capaextreme-theme. Los valores de atributos mostrados deben pasar por una función de escape comoesc_html(),esc_attr(),esc_url()owp_kses_post().echo.nonStringse deriva de la clave desconocida: un desplazamiento inexistente no tiene un tipo de cadena que se pueda mostrar.variable.undefinedaparece porque PHPStan ve un archivo de plantilla, no la función de renderizado que define$aantes de incluirlo. La sección de corrección lo explica.
Corregir el problema
Decida si subtitle es un campo real. Aquí sí lo es, así que declárelo con un default, ya que la capa del tema lo exige en todos los campos:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" },
{ "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
]
}
}
Escape la salida y declare $a con la estructura que infiere la extensión:
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Escriba la anotación con la estructura exacta. El comando canónico ejecuta PHPStan en el nivel max, donde se rechaza un @var array<string, mixed> $a menos estricto con varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). En 7.6 también amplía cada campo a mixed, por lo que cada llamada a esc_html() señala argument.type. El mensaje de varTag.nativeType muestra la estructura inferida, así que también es la forma más rápida de encontrar la anotación que debe copiar.
Blockstudio 7.7 considera que $a está definido dentro de las plantillas de bloque, por lo que desaparecen los diagnósticos de variable.undefined y la anotación pasa a ser opcional. Con 7.7, la plantilla rota de arriba muestra cuatro errores en lugar de seis y la plantilla corregida pasa sin la línea @var.
Elegir un preajuste
Al instalar el paquete, solo se habilita la extensión base. El comando canónico ejecuta base, salvo que el proyecto elija otro preajuste, así que añadir la dependencia no activa por sí solo las capas más estrictas.
| Preajuste | Añade |
|---|---|
base |
Acceso a campos de plantilla en PHP, Twig y Blade; comprobaciones de etiquetas de bloque; validación de esquemas para block.json, field.json, page.json, JSON, db.php, rpc.php y cron.php; rutas de Settings::get(); y nombres de hooks de blockstudio/*. |
theme |
Base más raíces del tema y encabezados de style.css, recursos declarados en block.json en lugar de añadidos manualmente a la cola, delimitación de %selector% en style.scss, valores predeterminados de campos y límites de repetidores. |
extreme-theme |
Tema más indicadores estrictos de PHPStan, llamadas a shell y eval() rechazadas, escrituras sin procesar de $wpdb, escape de salida y comprobaciones de Tailwind, JavaScript e API. |
wordpress-render |
Tema extremo más una prueba de renderizado en vivo que usted proporciona como comando. |
Si no se incluye una configuración del proyecto, el comando canónico también ejecuta base y theme con el nivel PHPStan max; extreme-theme establece por sí solo max. Cada diagnóstico de preajuste tiene un identificador estable de blockstudio.*, que figura en la referencia de PHPStan.
Las capas de tema y extremo también analizan archivos PHP. Si falta el default de un campo y hay un script.js que escribe en la consola, el mismo comando muestra:
------ -----------------------------------------------------------
Line blockstudio/hero/block.json
------ -----------------------------------------------------------
1 Blockstudio field "subtitle" must define a default value.
🪪 blockstudio.field.default
------ -----------------------------------------------------------
------ ------------------------------------------------------------
Line blockstudio/hero/script.js
------ ------------------------------------------------------------
2 Remove debug output "console.log" from shipped JavaScript.
🪪 blockstudio.javascript.debugOutput
------ ------------------------------------------------------------
Estas comprobaciones se notifican mediante la caché de resultados de PHPStan. Después de editar solo un block.json o un script, una caché activa puede notificar [OK] No errors para el estado anterior. Pase --debug después de -- para omitir la caché antes de confiar en un resultado correcto tras cambios que no sean de PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Opciones del comando y códigos de salida
Los valores de la línea de comandos sustituyen los valores correspondientes de blockstudio.json durante una ejecución. La sustitución es completa: al pasar cualquier --exclude, se descarta el excludePaths configurado, así que repita vendor/** si añade uno:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Todo lo que viene después de -- se pasa a PHPStan. El contenedor aumenta el límite de memoria de PHPStan a 1G, salvo que se pase un --memory-limit propio. Además, compone su configuración en el directorio temporal del sistema, así que no se genera ningún archivo en el proyecto. Termina con 0 si el análisis se completa correctamente, con 1 si PHPStan encuentra diagnósticos y con 2 si hay errores de uso, configuración o ejecución.
Ejecútelo mediante el comando canónico en lugar de añadir phpstan/extension-installer. Los preajustes ya incluyen la extensión y, si el instalador está presente, se carga dos veces el mismo extension.neon: PHPStan se detiene con «This file is included multiple times» antes de analizar nada.
Incorporarlo a un proyecto existente
Un proyecto analizado por primera vez suele tener hallazgos. En lugar de reducir el preajuste, regístrelos en una línea de base para que el código nuevo deba cumplir todas las reglas:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Incluya la línea de base desde la configuración del proyecto y apunte phpstan.configuration a ella:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
La siguiente ejecución informa [OK] No errors con los hallazgos registrados, y cualquier novedad sigue provocando un error. Con el preajuste base o theme, establezca también level: max dentro de parameters en phpstan.neon: el comando canónico solo establece ese nivel por sí mismo cuando no se incluye ninguna configuración del proyecto.
Condicionar los commits al análisis
Con "githooks": { "commit": true } en blockstudio.json, sincronice el hook administrado una vez después de instalar las dependencias:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
El comando escribe el hook en el propio directorio de Git, indica a core.hooksPath que lo use y encadena el hook de precommit que estuviera configurado antes. El hook ejecuta vendor/bin/blockstudio-phpstan -- --no-progress desde la raíz del proyecto y nada más: no aplica formato ni reescribe archivos. Al intentar confirmar el cambio de la plantilla rota de antes, el análisis lo detiene:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Establezca commit en false y vuelva a ejecutar sync, o ejecute vendor/bin/blockstudio-githooks remove para restaurar la ruta anterior del hook. Solo se eliminan los archivos que creó Blockstudio.
Generar el contrato del proyecto
El análisis le indica al agente después qué hizo mal. Un AGENTS.md se lo indica de antemano: dónde están los bloques y las páginas, cómo llegan los campos a las plantillas, qué funciones están habilitadas y qué rechazará el preajuste seleccionado. blockstudio-agents genera ese documento a partir del propio proyecto:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Para el tema de esta guía, el archivo generado empieza así:
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
Cada línea procede de uno de estos tres lugares. Los archivos del proyecto indican el tipo de proyecto, los recuentos, los directorios, los espacios de nombres y los lenguajes de plantilla. blockstudio.json indica las funciones habilitadas, por lo que el hook de commits aparece en «Funciones habilitadas» y vendor/bin/blockstudio-githooks sync aparece en «Comandos» solo porque está definido githooks.commit. La sección de corrección proviene del preajuste seleccionado y se lee de sus archivos capa por capa:
The `theme` layer adds:
- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.
Mantenerlo actualizado
El contrato queda desactualizado cuando cambia la configuración. Después de habilitar Tailwind en blockstudio.json, el modo de comprobación lo detecta:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Termina con 1, por lo que puede usarse como paso de CI junto al análisis. Al regenerar, se añade una entrada de función «Tailwind CSS» y el comando wp bs tailwind compile.
Notas que se conservan al regenerar
El archivo termina con una región para notas. Todo lo que queda entre sus marcadores se conserva byte por byte en cada regeneración, así que allí debe ir el conocimiento del proyecto que no se pueda deducir de los archivos:
## Project notes
Everything above is generated. Text between the markers below is preserved when this file is regenerated.
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
El generador nunca reemplaza un archivo que no haya creado. Si se ejecuta sobre un AGENTS.md escrito a mano, se niega y termina con 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Para conservar el texto escrito a mano, cópielo en otro lugar, ejecute con --force y péguelo en la región para notas. Las demás opciones son --root, --config, --output y --stdout, que muestra el contrato en lugar de escribirlo.
Cambios de Blockstudio 7.7
El paquete 7.7 conserva los comandos, los preajustes y los códigos de salida descritos aquí. Al preparar esta guía con esa versión, observamos dos diferencias: $a ya no necesita una anotación, como se explica en la sección de correcciones, y el contrato generado describe la validación de etiquetas de bloque de forma más amplia: abarca elementos HTML asignados a bloques en fuentes de página y los atributos globales que una etiqueta puede reenviar.
Pasos siguientes
- PHPStan referencia: cada regla, parámetro preestablecido, tipo de campo, forma, sonda de renderizado en vivo e identificador de diagnóstico.
- Integración con IA: el índice de documentación para agentes de programación que complementa el contrato de su proyecto.
- Programación intuitiva con Blockstudio: trabajar con agentes de programación en un proyecto de Blockstudio.
- Recetario de patrones de campos: estructuras de campos cuyas claves de plantilla entiende el análisis, incluidos grupos y campos repetidores.