Saltar al contenido

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

Shell
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:

Shell
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
<?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:

PHP
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:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "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.

Twig
<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.

Blade
<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.

HTML
<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:

JSON
{
  "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.

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$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.

PHP
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.

PHP
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 id en 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/checkbox sin options ni populate
  • IDs de campo duplicados
  • Un campo tabs dentro de un repetidor, directamente o dentro de un grupo sin id
  • Declaraciones pluginDependencies no 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:

Neon
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 attributes o está vacío
  • Objetos de atributo no válidos o falta type del campo
  • Falta id en campos de valor que lo requieren
  • Tipos de campo desconocidos
  • Propiedades de campo que el tipo de campo no acepta
  • Un campo tabs dentro de un repetidor, directamente o dentro de un grupo sin id
  • 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 postStatus no 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 public incorrecto (debe ser true, false o 'open')
  • Admite tanto arrays heredados como objetos devueltos con atributos

cron.php:

  • Falta schedule en las tareas configuradas
  • Falta callback en 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.

YAML
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:

YAML
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:

Shell
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:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "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:

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:

Shell
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:

  • 0 si el análisis se completa correctamente
  • 1 si PHPStan informa de diagnósticos
  • 2 si 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:

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:

Shell
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:

Shell
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:

Shell
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:

JSON
{"ok":true}

Una prueba puede informar de un fallo específico:

JSON
{
  "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.

Shell
vendor/bin/blockstudio-agents
Text
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.preset seleccionado. 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. En base describe las reglas de esquema, plantilla, hook y ajustes. En extreme-theme describe 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:

Shell
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:

Markdown
## 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.