Pular para o conteúdo

PHPStan

A extensão blockstudio/phpstan traz análise estática para projetos Blockstudio. Ela valida templates de bloco, arquivos de esquema, caminhos de configuração e nomes de hooks durante a análise, detectando erros antes que cheguem ao tempo de execução.

Instalação

Shell
composer require --dev blockstudio/phpstan

A tipagem de templates e as verificações ampliadas de tags de bloco da versão 7.7 exigem blockstudio/phpstan 0.1.9 ou mais recente e PHPStan 2.1.47 ou mais recente. Atualize o pacote separadamente do plugin:

Shell
composer require --dev blockstudio/phpstan:^0.1.9

A extensão é descoberta automaticamente pelo instalador de extensões de PHPStan. Não é necessária configuração manual.

O que ela verifica

Acesso a campos de template

Quando um arquivo PHP fica ao lado de um block.json, a extensão valida cada acesso $a['key'] em relação aos atributos declarados do bloco.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

A extensão sabe que Blockstudio define $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview e as variáveis de ilha antes de incluir um template. Assim, leituras diretas como $a['title'] não são sinalizadas como possivelmente indefinidas, e o tipo de $a é inferido de block.json ao lado do template. A estrutura é preservada ao restringir tipos, então $a['label'] ?? '', isset( $a['cta']['target'] ) e $a['cta']['title'] !== null mantêm os tipos de campo declarados; um template que atribui um valor à própria variável $a mantém o tipo atribuído. Não adicione um docblock /** @var array<string, mixed> $a */: ele substitui essa estrutura por um array aberto.

As chaves de campo seguem as regras de achatamento em tempo de execução de Blockstudio. tabs e contêineres group anônimos sem um id servem apenas para apresentação, então os campos filhos permanecem no escopo do pai. Um grupo nomeado acrescenta o ID do grupo como prefixo às chaves dos filhos:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Campos personalizados reutilizáveis

As referências custom/* baseadas em arquivos são expandidas antes da verificação das chaves de template e das estruturas de array. A extensão lê o field.json correspondente e aplica as mesmas regras de idStructure, overrides, referências aninhadas, grupos, abas e 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" }
        }
      }
    ]
  }
}

As chaves de template resultantes são title e hero_description. Elas são reconhecidas em PHP, Twig, Blade, tags de bloco e estruturas de atributos inferidas.

Definições baseadas em arquivos ausentes, ambíguas, inválidas ou cíclicas geram um erro blockstudio.customField.* específico. As verificações de chaves dependentes são ignoradas para esse bloco, evitando que uma definição não resolvida cause uma segunda onda de erros falsos de campo desconhecido.

Definições registradas apenas em tempo de execução pelo filtro blockstudio/fields PHP não podem ser inferidas pela análise estática. Use uma definição field.json quando o campo precisar fornecer chaves de template verificadas estaticamente.

Acesso a templates Twig

Os templates Twig são examinados automaticamente. Não é necessária nenhuma anotação.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Acesso a templates Blade

Os templates Blade são examinados da mesma forma.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Validação de tags de bloco

As tags de bloco são validadas onde Blockstudio as lê: tags <bs:> e <block>, tags com prefixo configuradas em blockTags.prefixes (como <acme-card>, resolvidas na ordem de namespace como em tempo de execução) e tags alias, em templates de bloco PHP, Twig e Blade, e em layouts de página. As fontes de páginas abaixo de pages/ (index.php, index.html, index.twig, index.blade.php) também são verificadas, incluindo os elementos HTML que o projeto mapeia para blocos. Os blocos UI incluídos são reconhecidos quando ui.enabled está ativado.

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) -->

Um atributo é aceito quando o bloco o declara como campo (incluindo campos personalizados e os campos encaminhados por um campo tipado como bloco sob seu idStructure), ou quando Blockstudio o encaminha ao elemento raiz do bloco: data-*, aria-*, id, style, role, title, lang, dir, hidden e tabindex. Em templates, todo atributo html-* é aceito; em fontes de página, um prefixo html- indica apenas um dos atributos encaminhados. Qualquer outro atributo é sinalizado, sobretudo um class não declarado, porque Blockstudio o armazena, mas nunca o renderiza.

O runtime registra mapeamentos de elementos e aliases de tags em filtros PHP, que a análise estática não pode avaliar; por isso, a análise os lê de blockstudio.json. scanPhp também verifica tags em outros PHP do projeto, como a marcação de componentes em módulos, sem sinalizar blocos desconhecidos nesses locais:

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
    }
  }
}

Um elemento é mapeado para um nome de bloco ou para regras testadas em ordem: vence a primeira regra cujo atributo o elemento contém, e um nome de bloco simples sempre corresponde. Elementos que o projeto não mapeia mantêm seu bloco do núcleo e não são verificados. Os diagnósticos usam blockstudio.blockTag.unknown, blockstudio.blockTag.attribute e blockstudio.blockTag.class.

Tipagem de registros do banco de dados

Db::get() retorna uma instância tipada com base no esquema db.php. As estruturas dos registros são inferidas automaticamente.

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

Campos obrigatórios não aceitam valores nulos. Campos opcionais são type|null. Um campo id (int) está sempre presente. A mesma tipagem funciona com a sintaxe de builder nativa de PHP Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Validação de caminhos de configurações

Os caminhos Settings::get() são verificados em relação ao esquema de configurações conhecido.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Validação de nomes de hooks

Os nomes de hooks de filtro e de ação Blockstudio são validados.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

Hooks de configuração dinâmicos, como blockstudio/settings/tailwind/enabled, são sempre permitidos. Hooks que não pertencem a blockstudio são ignorados.

Validação de esquemas

A extensão valida todos os arquivos de esquema Blockstudio do projeto.

block.json:

  • Campo name ausente
  • Campo type ausente
  • id ausente em campos de valor que exigem um
  • Tipos de campo desconhecidos
  • Propriedades de campo não aceitas pelo tipo de campo, como "translat" em vez de "translate", com a propriedade conhecida mais próxima como sugestão
  • select/radio/checkbox sem options ou populate
  • IDs de campo duplicados
  • Um campo tabs dentro de um repetidor, diretamente ou dentro de um grupo sem um id
  • Declarações pluginDependencies inválidas

Campos contêiner, como group e tabs, além de referências de campo custom/*, podem omitir id quando apenas expandem ou envolvem outros campos.

As propriedades dos campos são verificadas em relação às propriedades que schemas/block.json declara para cada tipo de campo integrado, além das propriedades aceitas por todos os campos. Propriedades específicas de wrappers em referências custom/* e tipos de campo com namespace definidos pelo projeto ficam fora dessa verificação. A validação existente de tipos de campo e referências personalizadas continua valendo. Os identificadores são blockstudio.blockJson.property e blockstudio.fieldJson.property.

Isso verifica os nomes das propriedades, não apenas seus valores: minimized é válido em um repetidor, mas é sinalizado em um campo de texto. O comportamento do plugin em tempo de execução não muda. Se um projeto anexar deliberadamente seus próprios metadados a campos integrados, suprima apenas esses apontamentos sem desativar outras verificações de estrutura:

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Os campos integrados dentro de um field.json reutilizável continuam sendo verificados, mesmo quando uma referência custom/* tem suas próprias opções de wrapper. Arquivos de extensão ficam fora do escopo desses diagnósticos de nomes de propriedade; as regras set específicas de extensões continuam válidas.

field.json (campos personalizados reutilizáveis):

  • Ausência de name
  • Ausência ou valor vazio em attributes
  • Objetos de atributo inválidos ou ausência do campo type
  • Ausência de id em campos de valor que exigem um
  • Tipos de campo desconhecidos
  • Propriedades que o tipo de campo não aceita
  • Um campo tabs dentro de um repetidor, diretamente ou em um grupo sem um id
  • Referências aninhadas custom/* ausentes, ambíguas, inválidas ou cíclicas

Extensão JSON (extensões de bloco em extensions/):

  • name ausente (bloco de destino)
  • Chave blockstudio ausente
  • Chave blockstudio.extend ausente

page.json (páginas baseadas em arquivos):

  • title ausente
  • slug ausente
  • Valores postStatus inválidos

db.php:

  • Array fields ausente
  • Tipos de campo inválidos
  • Compatível com arrays legados e com Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Métodos HTTP inválidos
  • Valor public incorreto (deve ser true, false ou 'open')
  • Compatível com arrays legados e retornos de objetos com atributos

cron.php:

  • Ausente schedule nas tarefas configuradas
  • Ausente callback nas tarefas configuradas
  • Compatível com retornos de arrays legados e objetos com atributos

blockstudio.json:

  • Booleanos abreviados como "tailwind": true (é necessário usar o formato de objeto aninhado {"enabled": true, "config": ""})

Configuração

Por padrão, a extensão localiza arquivos Blockstudio no projeto analisado. Quando um projeto usa blocos ou campos reutilizáveis de uma biblioteca fora da raiz do projeto, adicione o caminho da biblioteca a blockstudioScanRoots. O caminho é verificado em busca de definições de block.json e field.json, para que tags de blocos externos e seus campos personalizados possam ser validados em conjunto.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

Para ignorar arquivos, use a configuração padrão de excludePaths de PHPStan.

Predefinições de análise

A extensão descoberta automaticamente continua sendo a base segura para compatibilidade. Blockstudio 7.6 adiciona camadas opcionais sem alterar os projetos existentes:

Predefinição Comportamento
base.neon Análise existente de esquema, modelos, hooks, configurações e API.
theme.neon Base mais raízes de temas WordPress, cabeçalhos de estilo, recursos Blockstudio, escopo de seletores, valores padrão de campos e limites de repetidores.
extreme-theme.neon Tema mais PHPStan max, PHP inseguro, escape da saída, Tailwind, JavaScript e verificações de Interactivity API.
wordpress-render.neon Tema extremo mais uma sondagem de renderização WordPress ao vivo fornecida pelo chamador.

A instalação de blockstudio/phpstan habilita apenas a extensão base. Inclua uma camada opcional em uma configuração PHPStan existente:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePaths controla o verificador de temas. A configuração padrão de excludePaths de PHPStan controla a análise de PHP de forma independente.

A configuração phpstan.excludePaths do comando canônico em blockstudio.json (e sua opção --exclude) configura ambas as camadas. Os padrões relativos são resolvidos em relação a cada raiz configurada, então entradas como vendor/** limitam a análise de PHPStan, bem como a verificação do projeto de Blockstudio.

Um padrão que nomeia um único diretório, como _dist/** ou node_modules/**, exclui esse diretório onde quer que apareça, não apenas ao lado da raiz do tema. Um padrão com barra, como assets/*/docs/**, permanece ancorado à raiz. Os recursos de blocos compilados ficam em um diretório _dist dentro de cada bloco, por isso a forma de diretório único é a que mantém a saída compilada fora da análise.

Comando canônico

O pacote instala vendor/bin/blockstudio-phpstan como executável de análise. Ele executa a predefinição base, a menos que o projeto escolha outra, portanto instalar o pacote nunca habilita por si só as camadas de tema ou tema extremo:

Shell
vendor/bin/blockstudio-phpstan --root . -- --no-progress

As predefinições incluem a própria extensão. Não adicione phpstan/extension-installer a um projeto que executa o comando canônico: com o instalador presente, extension.neon é carregado duas vezes e PHPStan para com “This file is included multiple times” antes de analisar qualquer coisa.

Por padrão, o comando define PHPStan com um limite de memória 1G para que projetos WordPress gerenciados por Composer não herdem o limite típico de CLI 128M. Passe uma opção PHPStan explícita após -- para substituí-lo, como -- --memory-limit=512M --no-progress.

Adotar a análise em um projeto existente

Um projeto que nunca foi analisado geralmente apresentará descobertas na primeira execução. Em vez de reduzir a predefinição, gere uma linha de base PHPStan e indique phpstan.configuration a uma configuração do projeto que a inclua. Assim, o código novo fica sujeito à predefinição completa, enquanto as descobertas registradas não atrapalham:

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"
  }
}

Mantenha a linha level para as predefinições base e theme. O comando canônico só define o nível max para elas quando nenhuma configuração do projeto é incluída, e sem um nível PHPStan para com “No rules detected”. A predefinição extreme-theme define o nível max por conta própria.

Os caminhos relativos são resolvidos a partir de blockstudio.json. O comando canônico e o hook de commit gerenciado detectam o arquivo, portanto o hook impede novas descobertas sem exigir que o backlog seja eliminado primeiro.

Mantenha os padrões de comando para todo o projeto em blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

As raízes relativas são resolvidas a partir do arquivo que as declara. Valores explícitos de CLI substituem os valores correspondentes de JSON. Passe --blockstudio-json path/to/project.json para usar uma fonte de configuração alternativa. JSON malformado, chaves phpstan não compatíveis, valores inválidos e uma fonte explícita ausente resultam deterministicamente no código de saída 2.

Selecione outra predefinição, inclua uma configuração de projeto, adicione raízes repetíveis e exclusões ou peça a PHPStan JSON:

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

O wrapper compõe a configuração no diretório temporário do sistema e a exclui ao sair. Ele nunca grava configurações geradas, linhas de base, hooks ou caches no projeto analisado. Os chamadores ainda podem configurar explicitamente o cache normal de PHPStan.

O contrato de saída é:

  • 0 quando a análise é aprovada
  • 1 quando PHPStan relata diagnósticos
  • 2 para uso, configuração ou execução de processo inválidos

Gancho de commit gerenciado

Para tornar a análise de tema extremo uma barreira nos commits do repositório, habilite o hook gerenciado por Blockstudio em blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "githooks": {
    "commit": true
  }
}

Sincronize-o após instalar dependências ou alterar a configuração:

Shell
vendor/bin/blockstudio-githooks sync

O comando grava o hook de pre-commit gerado e o registro de propriedade dentro do diretório comum de Git, define core.hooksPath como o diretório do hook gerenciado e encadeia com segurança o hook de pre-commit previamente configurado. Sincronizações repetidas atualizam apenas o arquivo gerado, tornando as atualizações do pacote idempotentes.

Defina commit como false, remova-o ou remova blockstudio.json e execute sync para restaurar o caminho de hook registrado e excluir apenas os arquivos gerenciados por Blockstudio. Você também pode executar:

Shell
vendor/bin/blockstudio-githooks remove

Arquivos pertencentes ao usuário nunca são substituídos nem excluídos. Se alguém alterar core.hooksPath depois que Blockstudio tiver sido habilitado, a remoção preservará essa configuração mais recente. O hook gerado é compatível com checkouts Git vinculados e caminhos com espaços, pois resolve o repositório ativo e a raiz do projeto no momento do commit. Ele executa o comando canônico a partir dessa raiz, então o mesmo objeto phpstan controla execuções interativas e commits, sem argumentos gerados duplicados.

O hook executa apenas vendor/bin/blockstudio-phpstan. Blockstudio não executa um formatador, e o hook nunca reescreve arquivos do projeto. Dependências ausentes e falhas de análise bloqueiam o commit com um erro que indica como agir.

Renderização WordPress ao vivo

A camada ao vivo é deliberadamente explícita. O chamador é responsável pelo ambiente WordPress e fornece um 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 .

O comando é executado sem shell e deve imprimir um objeto JSON:

JSON
{"ok":true}

Uma sondagem pode relatar uma falha específica:

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

Saídas diferentes de zero, tempos limite, JSON malformado e ok: false geram blockstudio.wordpress.render.

blockstudio.javascript.domContract sinaliza um seletor de atributo [data-*] que um script passa para querySelector(), querySelectorAll(), closest() ou matches() quando nenhuma marcação analisada contém esse atributo. A marcação inclui todos os arquivos PHP, Twig, Blade e HTML e todos os componentes React .tsx e .jsx nas raízes analisadas, exceto os caminhos excluídos. Os componentes são analisados: nomes de atributos JSX contam, assim como as chaves de texto de literais de objeto. Portanto, um objeto de atributos espalhado em um elemento satisfaz o seletor, enquanto nomes de classes e outros valores de atributos não.

As verificações de Interactivity API leem os mesmos componentes React. Um namespace data-wp-interactive em um elemento JSX conta como referência de template para blockstudio.interactivity.orphan, e as diretivas data-wp-* dentro dele são resolvidas em relação ao namespace envolvente mais próximo ou a um prefixo namespace:: no valor. Diretivas com valor de texto estático, escritas como atributo JSX ou como chave de texto de um objeto de atributos, devem nomear manipuladores e caminhos de store existentes (blockstudio.interactivity.handler, blockstudio.interactivity.binding), e o código do store não deve alterar os atributos e as classes aos quais elas se vinculam (blockstudio.interactivity.derivedState). React escapa valores de atributos, então data-wp-context em um componente não é sinalizado, e valores dinâmicos não são verificados. Namespaces em bsui/ pertencem aos blocos UI incluídos, cujos stores são distribuídos com Blockstudio fora das raízes analisadas; por isso, nunca são órfãos.

Identificadores de diagnóstico

Os novos diagnósticos das predefinições mantêm IDs blockstudio.* estáveis:

  • Estrutura do tema: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Recursos e 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
  • Interatividade: 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

Desempenho

O verificador aceita diretórios materializados comuns, elimina raízes duplicadas, pula árvores de dependências, compilação e cache, mantém leituras de arquivos em cache na memória e ordena diagnósticos de forma determinística. Mantenha as raízes restritas, exclua árvores de fixtures/geradas e defina um limite de arquivos para repositórios grandes. JavaScript e Tailwind podem ser desativados de forma independente. A renderização ao vivo só é executada quando sua predefinição está selecionada.

Os diagnósticos de tema, JavaScript e Tailwind são relatados pelo cache de resultados de PHPStan. Depois de alterar apenas um block.json ou um script, um cache aquecido pode apresentar o resultado anterior. Passe --debug após -- para ignorar o cache ao verificar essas alterações.

Contrato do projeto para agentes de programação

O pacote instala um terceiro executável, vendor/bin/blockstudio-agents. Ele gera um AGENTS.md que descreve o projeto no qual está sendo executado, algo de que um agente de programação precisa antes de tocar em qualquer coisa: o que o projeto desenvolve, quais recursos de Blockstudio estão habilitados, o que a análise rejeitará e quais comandos se aplicam.

Shell
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Nada na saída é um modelo fixo. Cada linha deriva de uma destas três fontes:

  • Os próprios arquivos do projeto. Um tema com cabeçalho style.css, blocos e páginas baseadas em arquivos gera um documento diferente de um plugin que registra apenas blocos. As contagens, os diretórios, os namespaces dos blocos e as linguagens de modelos correspondem ao que o verificador realmente encontrou, usando as mesmas raízes e exclusões da análise.
  • blockstudio.json. São descritos apenas os recursos habilitados, com seus valores configurados: prefixos de tags de blocos e os namespaces pelos quais são resolvidos, Tailwind, o UI incluído, a redefinição de recursos do editor, o caminho do cache, o perfil de desempenho, a pré-renderização estática e seus caminhos dinâmicos, os padrões do tema, o Content Sync e o hook de commit.
  • A phpstan.preset selecionada. A seção de correção é lida diretamente dos arquivos das predefinições, camada por camada, e lista exatamente as regras que a predefinição registra. Em base, descreve as regras de esquema, modelo, hook e configurações. Em extreme-theme, também descreve as regras de estrutura do tema, as flags estritas de PHPStan, PHP inseguro, escape da saída, Tailwind e JavaScript. Quando uma predefinição ganha uma regra, o documento gerado também a inclui.

A seção de comandos segue o mesmo princípio. wp bs prerender status aparece quando a pré-renderização estática está habilitada, vendor/bin/blockstudio-githooks sync quando githooks.commit está definido, e wp bs db schemas quando o projeto realmente contém um db.php.

Opção Comportamento
--root <path> Raiz do projeto (padrão: diretório atual)
--config <path> Caminho de blockstudio.json (padrão: <root>/blockstudio.json)
--output <path> Caminho do contrato (padrão: <root>/AGENTS.md)
--stdout Imprime o contrato em vez de gravá-lo
--check Sai com 1 quando o contrato no disco está desatualizado
--force Substitui um arquivo que Blockstudio não controla

--check transforma o contrato em uma barreira de CI, assim como o hook de commit transforma a análise em uma:

Shell
vendor/bin/blockstudio-agents --check

Propriedade

O arquivo gerado contém o mesmo tipo de marcador que o hook de commit gerenciado, e a mesma regra se aplica: Blockstudio nunca substitui um arquivo que não criou. Um AGENTS.md anterior ao comando, ou escrito manualmente por um autor, é recusado com o código de saída 2 e permanece intacto até que --force seja passado.

A regeneração é segura. O arquivo termina com uma região de observações, e os bytes entre seus marcadores são preservados em todas as regenerações:

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

Os códigos de saída são 0 quando o contrato é gravado, está atualizado ou é impresso, 1 quando --check encontra um contrato desatualizado, e 2 para erros de uso, configuração ou sistema de arquivos.

Formatos dos tipos de campo

A extensão mapeia cada tipo de campo Blockstudio para um tipo PHP concreto:

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últiplo) 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últiplo) list<array{id: int, url: string, ...}>
group Grupos nomeados usam prefixos de sublinhado; grupos anônimos são incorporados ao escopo pai
repeater list<array{...child fields...}>
tabs Incorporado ao escopo pai

Stubs de API

A extensão inclui stubs para toda a API pública de API de Blockstudio:

  • 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()

Eles oferecem preenchimento automático e verificação de tipos sem precisar ter o código-fonte do plugin Blockstudio na sua máquina.

Requisitos

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (recomendado para descoberta automática)

O pacote instala automaticamente seu provedor de compatibilidade BC Math. Portanto, ext-bcmath nativo é opcional, inclusive para temas recém-gerados que habilitam as verificações JavaScript por meio da predefinição de tema ou de tema extremo.