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
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:
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
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:
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:
{
"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" }
}
}
]
}
}
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.
<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.
<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.
<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:
{
"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.
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
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.
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.
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
nameausente - Campo
typeausente idausente 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/checkboxsemoptionsoupopulate- IDs de campo duplicados
- Um campo
tabsdentro de um repetidor, diretamente ou dentro de um grupo sem umid - Declarações
pluginDependenciesinvá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:
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
idem campos de valor que exigem um - Tipos de campo desconhecidos
- Propriedades que o tipo de campo não aceita
- Um campo
tabsdentro de um repetidor, diretamente ou em um grupo sem umid - Referências aninhadas
custom/*ausentes, ambíguas, inválidas ou cíclicas
Extensão JSON (extensões de bloco em extensions/):
nameausente (bloco de destino)- Chave
blockstudioausente - Chave
blockstudio.extendausente
page.json (páginas baseadas em arquivos):
titleausenteslugausente- Valores
postStatusinválidos
db.php:
- Array
fieldsausente - 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
publicincorreto (deve sertrue,falseou'open') - Compatível com arrays legados e retornos de objetos com atributos
cron.php:
- Ausente
schedulenas tarefas configuradas - Ausente
callbacknas 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.
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:
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:
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:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"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:
{
"$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:
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 é:
0quando a análise é aprovada1quando PHPStan relata diagnósticos2para 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:
{
"$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:
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:
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:
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:
{"ok":true}
Uma sondagem pode relatar uma falha específica:
{
"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.
vendor/bin/blockstudio-agents
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.presetselecionada. 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. Embase, descreve as regras de esquema, modelo, hook e configurações. Emextreme-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:
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:
## 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.