PHPStan
La extensión blockstudio/phpstan incorpora el análisis estático a los proyectos Blockstudio. Valida las plantillas de bloques, los archivos de esquema, las rutas de configuración y los nombres de hooks durante el análisis, y detecta errores antes de que lleguen al tiempo de ejecución.
Instalación
composer require --dev blockstudio/phpstan
La tipificación de plantillas de la versión 7.7 y las comprobaciones ampliadas de etiquetas de bloques requieren blockstudio/phpstan 0.1.9 o una versión posterior y PHPStan 2.1.47 o una versión posterior. Actualiza el paquete por separado del plugin:
composer require --dev blockstudio/phpstan:^0.1.9
La extensión se detecta automáticamente mediante el instalador de extensiones de PHPStan. No hace falta configurarla manualmente.
Qué comprueba
Acceso a campos de plantilla
Cuando un archivo PHP está junto a un block.json, la extensión valida cada acceso a $a['key'] con respecto a los atributos declarados del bloque.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
La extensión sabe que Blockstudio define $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview y las variables de isla antes de incluir una plantilla, así que las lecturas directas como $a['title'] no se notifican como posiblemente indefinidas, y el tipo de $a se infiere del block.json junto a la plantilla. La estructura se conserva al restringir el tipo, por lo que $a['label'] ?? '', isset( $a['cta']['target'] ) y $a['cta']['title'] !== null mantienen los tipos de campo declarados; una plantilla que asigna un valor a $a conserva el tipo que le asignó. No añadas un bloque de documentación /** @var array<string, mixed> $a */: sustituye esa estructura por una matriz abierta.
Las claves de campo siguen las reglas de aplanamiento en tiempo de ejecución de Blockstudio. tabs y los contenedores group anónimos sin id solo sirven para la presentación, así que sus campos secundarios permanecen en el ámbito del elemento principal. Un grupo con nombre antepone su ID a las claves de sus campos secundarios:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Campos personalizados reutilizables
Las referencias custom/* respaldadas por archivos se expanden antes de comprobar las claves de plantilla y las estructuras de matrices. La extensión lee el field.json correspondiente y aplica las mismas reglas de idStructure, overrides, referencias anidadas, grupos, pestañas y repetidores que Blockstudio:
{
"name": "mytheme/hero",
"attributes": [
{ "id": "heading", "type": "text" },
{ "id": "description", "type": "textarea" }
]
}
{
"blockstudio": {
"attributes": [
{
"type": "custom/mytheme/hero",
"idStructure": "hero_{id}",
"overrides": {
"heading": { "id": "title" }
}
}
]
}
}
Las claves de plantilla resultantes son title y hero_description. Se reconocen en PHP, Twig, Blade, las etiquetas de bloque y las estructuras de atributos inferidas.
Las definiciones respaldadas por archivos que falten, sean ambiguas, no válidas o cíclicas producen un error específico de blockstudio.customField.*. Se omiten las comprobaciones de claves dependientes para ese bloque, de modo que una definición sin resolver no provoque otra serie de errores falsos por campos desconocidos.
El análisis estático no puede inferir las definiciones registradas solo en tiempo de ejecución mediante el filtro blockstudio/fields PHP. Usa una definición field.json cuando el campo deba aportar claves de plantilla con comprobación estática.
Acceso a plantillas Twig
Las plantillas Twig se analizan automáticamente. No hace falta ninguna anotación.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Acceso a plantillas Blade
Las plantillas Blade se analizan del mismo modo.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Validación de etiquetas de bloques
Las etiquetas de bloques se validan en los lugares donde Blockstudio las lee: en las etiquetas <bs:> y <block>; las etiquetas de prefijo configuradas en blockTags.prefixes (como <acme-card>, que se resuelven en el orden de los espacios de nombres, igual que en tiempo de ejecución); y las etiquetas de alias, en las plantillas de bloques PHP, Twig y Blade, así como en los diseños de página. También se comprueban las fuentes de páginas situadas bajo pages/ (index.php, index.html, index.twig y index.blade.php), incluidos los elementos HTML que el proyecto asigna a bloques. Los bloques UI incluidos se reconocen cuando ui.enabled está activado.
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->
Se acepta un atributo cuando el bloque lo declara como campo (incluidos los campos personalizados y los campos que un campo tipado como bloque transmite bajo su idStructure), o cuando Blockstudio lo transmite al elemento raíz del bloque: data-*, aria-*, id, style, role, title, lang, dir, hidden y tabindex. En las plantillas se transmite cada atributo html-*; en las fuentes de página, un prefijo html- solo designa uno de los atributos transmitidos. Se notifican todos los demás atributos, especialmente los class no declarados, porque Blockstudio los almacena pero nunca los representa.
El entorno de ejecución registra las asignaciones de elementos y los alias de etiquetas en filtros PHP, que el análisis estático no puede evaluar; por eso, el análisis los lee de blockstudio.json. scanPhp también comprueba las etiquetas de otros PHP del proyecto, como el marcado de componentes en módulos, sin notificar bloques desconocidos en ellos:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Un elemento se asigna a un nombre de bloque o a reglas que se prueban en orden: gana la primera regla cuyo atributo lleva el elemento, y un nombre de bloque sin condiciones siempre coincide. Los elementos que el proyecto no asigna conservan su bloque principal y no se comprueban. Los diagnósticos usan blockstudio.blockTag.unknown, blockstudio.blockTag.attribute y blockstudio.blockTag.class.
Tipado de registros de base de datos
Db::get() devuelve una instancia tipada según el esquema db.php. Las estructuras de los registros se infieren automáticamente.
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);
echo $record['email']; // string
echo $record['name']; // string|null (optional field)
echo $record['typo']; // Error: Offset 'typo' does not exist
Los campos obligatorios no aceptan valores nulos. Los campos opcionales son type|null. Un campo id (int) siempre está presente. El mismo tipado funciona con la sintaxis del generador Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field nativa de PHP.
Validación de rutas de ajustes
Las rutas Settings::get() se comprueban con respecto al esquema de configuración conocido.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Validación de nombres de hooks
Se validan los nombres de filtros y hooks de acción Blockstudio.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Los hooks de configuración dinámica como blockstudio/settings/tailwind/enabled siempre están permitidos. Se ignoran los hooks que no sean de blockstudio.
Validación de esquemas
La extensión valida todos los archivos de esquema Blockstudio del proyecto.
block.json:
- Falta el campo
name - Falta el campo
type - Falta
iden los campos de valor que lo requieren - Tipos de campo desconocidos
- Propiedades que el tipo de campo no admite, como
"translat"en lugar de"translate", con una sugerencia de la propiedad conocida más cercana select/radio/checkboxsinoptionsnipopulate- IDs de campo duplicados
- Un campo
tabsdentro de un repetidor, directamente o dentro de un grupo sinid - Declaraciones
pluginDependenciesno válidas
Los campos contenedores, como group y tabs, además de las referencias de campo custom/*, pueden omitir id cuando solo expanden o envuelven otros campos.
Las propiedades de los campos se comprueban frente a las propiedades que schemas/block.json declara para cada tipo de campo integrado, además de las propiedades que acepta cualquier campo. Las propiedades específicas de los envoltorios en las referencias custom/* y los tipos de campo con espacio de nombres definidos por el proyecto quedan fuera de esta comprobación. La validación existente de tipos de campo y referencias personalizadas sigue aplicándose. Los identificadores son blockstudio.blockJson.property y blockstudio.fieldJson.property.
Esto comprueba los nombres de las propiedades, no solo sus valores: minimized es válido en un repetidor, pero se notifica en un campo de texto. El comportamiento del complemento en tiempo de ejecución no cambia. Si un proyecto añade deliberadamente sus propios metadatos a campos integrados, suprima solo estos avisos sin desactivar otras comprobaciones de estructura:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Los campos integrados dentro de un field.json reutilizable siguen comprobándose, incluso cuando una referencia custom/* tiene sus propias opciones de envoltorio. Los archivos de extensión quedan fuera del alcance de estos diagnósticos de nombres de propiedades; las reglas set específicas de las extensiones siguen siendo válidas.
field.json (campos personalizados reutilizables):
- Falta
name - Falta
attributeso está vacío - Objetos de atributo no válidos o falta
typedel campo - Falta
iden campos de valor que lo requieren - Tipos de campo desconocidos
- Propiedades de campo que el tipo de campo no acepta
- Un campo
tabsdentro de un repetidor, directamente o dentro de un grupo sinid - Referencias anidadas
custom/*inexistentes, ambiguas, no válidas o cíclicas
Extensión JSON (extensiones de bloques en extensions/):
- Falta
name(bloque de destino) - Falta la clave
blockstudio - Falta la clave
blockstudio.extend
page.json (páginas basadas en archivos):
- Falta
title - Falta
slug - Valores de
postStatusno válidos
db.php:
- Falta el array
fields - Tipos de campo no válidos
- Admite tanto arrays heredados como
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Métodos HTTP no válidos
- Valor
publicincorrecto (debe sertrue,falseo'open') - Admite tanto arrays heredados como objetos devueltos con atributos
cron.php:
- Falta
scheduleen las tareas configuradas - Falta
callbacken las tareas configuradas - Admite tanto arrays heredados como objetos devueltos con atributos
blockstudio.json:
- Valores booleanos abreviados como
"tailwind": true(debe usarse el formato de objeto anidado{"enabled": true, "config": ""})
Configuración
La extensión descubre de forma predeterminada los archivos Blockstudio del proyecto analizado.
Si el proyecto usa bloques o campos reutilizables de una biblioteca fuera de la
raíz del proyecto, añade la ruta de la biblioteca a blockstudioScanRoots. La ruta se
analiza en busca de definiciones de block.json y field.json, para que las etiquetas de
bloques externos y sus campos personalizados puedan validarse conjuntamente.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Para ignorar archivos, usa la configuración estándar de excludePaths de PHPStan.
Ajustes preestablecidos de análisis
La extensión descubierta automáticamente sigue siendo la base compatible. Blockstudio 7.6 añade capas opcionales sin cambiar los proyectos existentes:
| Ajuste preestablecido | Comportamiento |
|---|---|
base.neon |
Análisis existente de esquemas, plantillas, hooks, ajustes y API. |
theme.neon |
La base más raíces de temas WordPress, encabezados de estilos, recursos Blockstudio, alcance de selectores, valores predeterminados de campos y límites de repetidores. |
extreme-theme.neon |
El tema más PHPStan max, PHP no seguros, escape de salida, Tailwind, JavaScript y comprobaciones de Interactivity API. |
wordpress-render.neon |
El tema extremo más una prueba de renderizado WordPress en vivo proporcionada por quien realiza la llamada. |
Instalar blockstudio/phpstan habilita solo la extensión base. Incluye una capa opcional en una configuración PHPStan existente:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths controla el analizador de temas.
La configuración estándar de PHPStan en excludePaths controla el análisis de PHP de forma independiente.
El ajuste phpstan.excludePaths del comando canónico en blockstudio.json
(y su opción --exclude) configura ambas capas. Los patrones relativos se resuelven
respecto a cada raíz configurada, así que entradas como vendor/** limitan el análisis
de PHPStan y también el análisis del proyecto de Blockstudio.
Un patrón que indica un único directorio, como _dist/** o node_modules/**,
excluye ese directorio dondequiera que aparezca, no solo junto a la raíz del tema. Un
patrón que contiene una barra, como assets/*/docs/**, permanece anclado a la raíz. Los recursos
de bloques generados están en un directorio _dist dentro de cada bloque, así que
el formato de directorio único es el que mantiene el resultado compilado fuera del análisis.
Comando canónico
El paquete instala vendor/bin/blockstudio-phpstan como ejecutable de análisis.
Ejecuta el ajuste preestablecido base, salvo que el proyecto seleccione otro, por lo que
instalar el paquete nunca habilita por sí solo las capas de tema o tema extremo:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Los ajustes preestablecidos incluyen la extensión. No añadas
phpstan/extension-installer a un proyecto que ejecute el comando canónico:
con el instalador presente, extension.neon se carga dos veces y PHPStan se detiene
con «This file is included multiple times» antes de analizar nada.
El comando establece PHPStan de forma predeterminada en un límite de memoria 1G para que los proyectos WordPress administrados por Composer no hereden el límite habitual de 128M CLI. Pasa una opción PHPStan explícita después de -- para anularlo, como -- --memory-limit=512M --no-progress.
Incorporar el análisis a un proyecto existente
Un proyecto que nunca se ha analizado normalmente mostrará hallazgos en la primera
ejecución. En lugar de bajar el ajuste preestablecido, genera una línea base PHPStan y configura
phpstan.configuration para que apunte a una configuración del proyecto que la incluya. Así, el código nuevo
se somete al ajuste preestablecido completo y los hallazgos registrados no interfieren:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Mantén la línea level para los ajustes preestablecidos base y theme. El comando canónico
solo establece el nivel max para ellos si no se incluye una configuración del proyecto, y
sin un nivel PHPStan se detiene con «No rules detected». El ajuste preestablecido extreme-theme
establece por sí mismo el nivel max.
Las rutas relativas se resuelven desde blockstudio.json. Tanto el comando canónico como el
hook de confirmación administrado recogen el archivo, así que el hook bloquea los hallazgos
nuevos sin exigir que primero se resuelva el trabajo pendiente.
Mantén los valores predeterminados del comando para todo el proyecto en blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Las raíces relativas se resuelven desde el archivo que las declara. Los valores explícitos de CLI
reemplazan los valores correspondientes de JSON. Pasa
--blockstudio-json path/to/project.json para indicar otra fuente de configuración.
Una configuración JSON malformada, claves phpstan no admitidas, valores no válidos y la
falta de una fuente explícita producen un error determinista con el código de salida 2.
Selecciona otro ajuste preestablecido, incluye una configuración del proyecto, añade raíces y exclusiones repetibles, o solicita a PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
El contenedor combina la configuración en el directorio temporal del sistema y la elimina al salir. Nunca escribe configuraciones generadas, líneas base, hooks o cachés en el proyecto analizado. Quienes realizan llamadas pueden configurar igualmente la caché normal de PHPStan de forma explícita.
El contrato de salida es:
0si el análisis se completa correctamente1si PHPStan informa de diagnósticos2si el uso, la configuración o la ejecución del proceso no son válidos
Hook de commit administrado
Para convertir el análisis de tema extremo en una condición para confirmar cambios en el repositorio, habilita el hook administrado por Blockstudio en blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Sincronízalo después de instalar dependencias o cambiar el ajuste:
vendor/bin/blockstudio-githooks sync
El comando escribe el hook de preconfirmación generado y el registro de propiedad dentro
del directorio común de Git, establece core.hooksPath en el directorio del hook administrado
y encadena de forma segura el hook de preconfirmación configurado anteriormente. Las sincronizaciones repetidas
actualizan solo el archivo generado, por lo que las actualizaciones del paquete son idempotentes.
Establece commit en false, elimínalo o elimina blockstudio.json y luego ejecuta
sync para restaurar la ruta del hook registrada y borrar solo los archivos propiedad de Blockstudio.
También puedes ejecutar:
vendor/bin/blockstudio-githooks remove
Los archivos propiedad del usuario nunca se sobrescriben ni se eliminan. Si alguien cambia
core.hooksPath después de habilitar Blockstudio, al desinstalar se conserva ese ajuste más reciente.
El hook generado admite checkouts Git enlazados y rutas con espacios, ya que resuelve el repositorio activo y la raíz del proyecto al confirmar. Ejecuta el comando canónico desde esa raíz, así que el mismo objeto phpstan controla las ejecuciones interactivas y las confirmaciones sin duplicar los argumentos generados.
El hook ejecuta solo vendor/bin/blockstudio-phpstan. Blockstudio no ejecuta un
formateador y el hook nunca reescribe archivos del proyecto. Las dependencias que falten y los
fallos de análisis bloquean la confirmación con un error que indica cómo resolverlo.
Renderizado WordPress en vivo
La capa en vivo es explícita a propósito. Quien realiza la llamada se encarga del entorno WordPress y proporciona un array argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
El comando se ejecuta sin un shell y debe mostrar un objeto JSON:
{"ok":true}
Una prueba puede informar de un fallo específico:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Las salidas distintas de cero, los tiempos de espera agotados, JSON malformado y ok: false producen blockstudio.wordpress.render.
blockstudio.javascript.domContract informa de un selector de atributo [data-*] que un script pasa a querySelector(), querySelectorAll(), closest() o matches() cuando ningún marcado analizado contiene ese atributo. El marcado incluye todos los archivos PHP, Twig, Blade y HTML, así como todos los componentes React .tsx y .jsx bajo las raíces analizadas, excepto las rutas excluidas. Los componentes se analizan: cuentan los nombres de atributo JSX y también las claves de cadena de los literales de objeto. Por tanto, un objeto de atributos extendido sobre un elemento satisface el selector, mientras que los nombres de clase y otros valores de atributo no lo hacen.
Las comprobaciones de Interactivity API leen los mismos componentes React. Un espacio de nombres data-wp-interactive en un elemento JSX cuenta como referencia de plantilla para blockstudio.interactivity.orphan, y las directivas data-wp-* que contiene se resuelven con el espacio de nombres contenedor más cercano o con un prefijo namespace:: en el valor. Las directivas con un valor de cadena estático, escritas como atributo JSX o como clave de cadena de un objeto de atributos, deben indicar controladores y rutas de almacén existentes (blockstudio.interactivity.handler, blockstudio.interactivity.binding), y el código del almacén no debe modificar los atributos ni las clases a los que están enlazadas (blockstudio.interactivity.derivedState). React escapa los valores de atributo, así que data-wp-context en un componente no se informa, y los valores dinámicos no se comprueban. Los espacios de nombres bajo bsui/ pertenecen a los bloques UI incluidos, cuyos almacenes se distribuyen con Blockstudio fuera de las raíces analizadas, por lo que nunca quedan huérfanos.
Identificadores de diagnóstico
Los nuevos diagnósticos de los ajustes preestablecidos conservan IDs blockstudio.* estables:
- Estructura del tema:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Recursos y campos:
blockstudio.theme.asset.manualEnqueue,blockstudio.theme.asset.selectorScope,blockstudio.theme.asset.missing,blockstudio.field.default,blockstudio.field.repeaterBounds - PHP:
blockstudio.php.forbiddenFunction,blockstudio.wordpress.rawDatabaseWrite,blockstudio.output.unescaped - Tailwind:
blockstudio.tailwind.compilerMissing,blockstudio.tailwind.compile,blockstudio.tailwind.unknownUtility,blockstudio.tailwind.semanticToken - JavaScript:
blockstudio.javascript.syntax,blockstudio.javascript.debugOutput,blockstudio.javascript.bannedApi,blockstudio.javascript.leakedGlobal,blockstudio.javascript.importSpecifier,blockstudio.javascript.rootGuard,blockstudio.javascript.initShape,blockstudio.javascript.domContract,blockstudio.javascript.listenerCleanup,blockstudio.javascript.reducedMotion - Interactividad:
blockstudio.interactivity.import,blockstudio.interactivity.moduleImport,blockstudio.interactivity.namespace,blockstudio.interactivity.scopedDom,blockstudio.interactivity.derivedState,blockstudio.interactivity.handler,blockstudio.interactivity.binding,blockstudio.interactivity.context,blockstudio.interactivity.orphan
Rendimiento
El analizador acepta directorios materializados habituales, deduplica raíces, omite árboles de dependencias, compilaciones y cachés, almacena lecturas de archivos en memoria y ordena los diagnósticos de forma determinista. Mantén las raíces acotadas, excluye árboles de pruebas y generados, y establece un límite de archivos para repositorios grandes. JavaScript y Tailwind se pueden deshabilitar de forma independiente. El renderizado en vivo solo se ejecuta si se selecciona su ajuste preestablecido.
Los diagnósticos de tema, JavaScript y Tailwind se informan a través de la caché de resultados de PHPStan.
Si solo cambias un block.json o un script, una caché activa puede informar del resultado anterior. Pasa
--debug después de -- para omitir la caché al verificar esos cambios.
Contrato del proyecto para agentes de programación
El paquete instala un tercer ejecutable, vendor/bin/blockstudio-agents. Escribe un AGENTS.md que describe el proyecto en el que se ejecuta; es lo que un agente de programación necesita antes de modificar nada: qué crea el proyecto, qué funciones de Blockstudio están habilitadas, qué rechazará el análisis y qué comandos se aplican.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Nada en la salida es una plantilla fija. Cada línea se deriva de una de estas tres fuentes:
- Los propios archivos del proyecto. Un tema con un encabezado
style.css, bloques y páginas basadas en archivos genera un documento distinto al de un plugin que solo registra bloques. Los recuentos, directorios, espacios de nombres de bloques y lenguajes de plantillas son los que realmente encontró el analizador, que usa las mismas raíces y exclusiones que el análisis. blockstudio.json. Solo se describen las funciones habilitadas, con sus valores configurados: prefijos de etiquetas de bloques y los espacios de nombres a los que se resuelven, Tailwind, el UI incluido, el restablecimiento de recursos del editor, la ruta de caché, el perfil de rendimiento, el prerenderizado estático y sus rutas dinámicas, los valores predeterminados del tema, Content Sync y el hook de confirmación.- El
phpstan.presetseleccionado. La sección de corrección se lee directamente de los archivos de ajustes preestablecidos, capa por capa, y enumera exactamente las reglas que registra ese ajuste. Enbasedescribe las reglas de esquema, plantilla, hook y ajustes. Enextreme-themedescribe también las reglas de estructura del tema, los indicadores estrictos PHPStan, PHP no seguros, el escape de salida, Tailwind y JavaScript. Si se añade una regla a un ajuste preestablecido, también cambia el documento generado.
La sección de comandos sigue el mismo principio. wp bs prerender status aparece cuando el prerenderizado estático está habilitado, vendor/bin/blockstudio-githooks sync cuando se establece githooks.commit y wp bs db schemas cuando el proyecto tiene realmente un db.php.
| Opción | Comportamiento |
|---|---|
--root <path> |
Raíz del proyecto (predeterminada: directorio actual) |
--config <path> |
Ruta de blockstudio.json (predeterminada: <root>/blockstudio.json) |
--output <path> |
Ruta del contrato (predeterminada: <root>/AGENTS.md) |
--stdout |
Imprimir el contrato en lugar de escribirlo |
--check |
Salir con 1 si el contrato en disco no está actualizado |
--force |
Reemplazar un archivo del que Blockstudio no es propietario |
--check convierte el contrato en una condición de CI, del mismo modo que el hook de confirmación convierte el análisis en una:
vendor/bin/blockstudio-agents --check
Propiedad
El archivo generado lleva el mismo tipo de marcador que el hook de confirmación administrado,
y se aplica la misma regla: Blockstudio nunca reemplaza un archivo que no haya escrito.
Si AGENTS.md ya existía antes del comando o lo escribió manualmente una persona autora,
se rechaza con el código de salida 2 y queda intacto hasta que se pase --force.
Regenerar es seguro. El archivo termina con una sección de notas y los bytes situados entre sus marcadores se conservan en cada regeneración:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Los códigos de salida son 0 cuando se escribe, está actualizado o se imprime el contrato, 1 cuando
--check encuentra un contrato obsoleto y 2 si hay errores de uso, configuración o
sistema de archivos.
Estructuras de tipos de campo
La extensión asigna a cada tipo de campo Blockstudio un tipo concreto de PHP:
| Tipo de campo | Tipo PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (único) |
string|int |
select, checkbox (múltiple) |
list<string|int> |
color |
array{value: string, opacity: float|null} |
link |
array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null} |
icon |
array{set: string, subSet: string, icon: string} |
files (único) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (múltiple) |
list<array{id: int, url: string, ...}> |
group |
Los grupos con nombre usan prefijos de guion bajo; los grupos anónimos se aplanan en el ámbito principal |
repeater |
list<array{...child fields...}> |
tabs |
Se aplana en el ámbito principal |
Stubs de API
La extensión incluye stubs para toda la API pública de Blockstudio API:
bs_render_block(),bs_block_values(),bs_get_group(),bs_get_scoped_class(),bs_db_form(),bs_is_editor(),bs_is_preview(),bs_is_buffering(),bs_strip_render_markers()Db::get(),Db::create(),Db::list(),Db::get_record(),Db::update(),Db::delete()Settings::get(),Settings::get_all()Field_Registry::instance(),Field_Registry::all(),Field_Registry::get()Build::blocks(),Build::extensions(),Build::get_build_dir()
Estos proporcionan autocompletado y comprobación de tipos sin necesidad de tener el código fuente del plugin Blockstudio en el equipo.
Requisitos
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(recomendado para el descubrimiento automático)
El paquete instala automáticamente su proveedor de compatibilidad BC Math. Por tanto,
ext-bcmath es opcional, incluso para temas recién generados que
habilitan las comprobaciones JavaScript mediante el ajuste de tema o tema extremo.