Templates validados com PHPStan e um AGENTS.md gerado
Um bloco Blockstudio consiste em dois arquivos que precisam estar de acordo. O block.json declara os campos, e o template os lê como $a['id']. Nada em tempo de execução impede o template de ler uma chave que foi renomeada, nunca declarada ou escrita incorretamente. Ele simplesmente renderiza uma string vazia, e o erro só é percebido quando alguém nota um título em branco em uma página publicada. O mesmo vale para o escape da saída: um echo sem escape funciona perfeitamente até que um valor de campo contenha marcação.
O pacote blockstudio/phpstan transfere ambos os problemas para o momento da análise. Ele lê seus arquivos block.json, infere os tipos de $a a partir deles e relata leituras de template incompatíveis. Seus presets opcionais adicionam regras de estrutura do tema, escape e verificações de JavaScript e Tailwind. O mesmo pacote inclui dois complementos: um hook de pre-commit gerenciado que executa a análise e um gerador que cria um AGENTS.md descrevendo seu projeto para agentes de código.
Este guia cria um tema pequeno, quebra deliberadamente um de seus templates, examina a saída da análise, corrige o problema e, em seguida, configura o bloqueio de commits e o contrato para agentes.
Configure o tema
Comece com uma pasta de tema que tenha um cabeçalho style.css, um composer.json e um bloco:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Instale o pacote como uma dependência de desenvolvimento:
composer require --dev blockstudio/phpstan
Ele instala PHPStan e os stubs WordPress de szepeviktor/phpstan-wordpress, além de três executáveis em vendor/bin: blockstudio-phpstan, blockstudio-githooks e blockstudio-agents.
Em seguida, informe à análise o que deve ser executado. Os valores padrão para todo o projeto ficam no objeto phpstan de blockstudio.json, para que as execuções interativas, o CI e o hook de commit leiam as mesmas configurações:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme é o mais rigoroso dos três presets estáticos. A tabela abaixo explica o que cada um acrescenta. excludePaths mantém os próprios arquivos de Composer fora da análise de Blockstudio e de PHP.
Quebre um template de propósito
O bloco principal declara um único campo:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
O template lê corretamente esse campo, mas depois lê um subtitle que o bloco nunca declarou e o imprime sem escape:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
No editor e no frontend, isso renderiza um parágrafo vazio sem gerar nenhum erro. Execute a análise:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
Line blockstudio/hero/index.php
------ -------------------------------------------------------------------
2 Variable $a might not be defined.
🪪 variable.undefined
3 Dynamic Blockstudio attributes must be escaped before output.
🪪 blockstudio.output.unescaped
3 Field "subtitle" does not exist in block.json (block: acme/hero).
🪪 blockstudio.field
3 Offset 'subtitle' does not exist on array{heading: string}.
🪪 offsetAccess.notFound
3 Parameter #1 (mixed) of echo cannot be converted to string.
🪪 echo.nonString
3 Variable $a might not be defined.
🪪 variable.undefined
------ -------------------------------------------------------------------
[ERROR] Found 6 errors
O comando termina com 1. Veja os diagnósticos, do mais específico ao mais abrangente:
blockstudio.fieldé a regra do template. Ela encontrou oblock.jsonao lado do template, identificou seus campos e verificou quesubtitlenão está entre eles.offsetAccess.notFoundé o próprio PHPStan chegando à mesma conclusão, porque a extensão fornece a$aa estrutura concretaarray{heading: string}, derivada deblock.json. Cada tipo de campo corresponde a um tipo PHP:texté umstring,toggleé umbool, e um repetidor é um array de estruturas de linha.blockstudio.output.unescapedvem da camadaextreme-theme. Os valores de atributos impressos devem passar por uma função de escape, comoesc_html(),esc_attr(),esc_url()ouwp_kses_post().echo.nonStringdecorre da chave desconhecida: um deslocamento inexistente não tem tipo string para ser impresso.variable.undefinedaparece porque PHPStan encontra um arquivo de template, e não a função de renderização que define$aantes de incluí-lo. A seção de correção aborda isso.
Corrija o problema
Determine se subtitle é um campo real. Neste caso, é; então, declare-o com um default, pois a camada do tema exige um em cada campo:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" },
{ "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
]
}
}
Faça o escape da saída e declare $a com a estrutura inferida pela extensão:
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Escreva a anotação com a estrutura exata. O comando canônico executa PHPStan no nível max, no qual um @var array<string, mixed> $a menos específico é rejeitado com varTag.nativeType (“A tag PHPDoc @var com tipo array<string, mixed> não é subtipo do tipo nativo array{heading: string, subtitle: string}”). Na versão 7.6, cada campo também passa a ter o tipo mixed, então cada chamada de esc_html() relata argument.type. A mensagem varTag.nativeType exibe a estrutura inferida, sendo também a forma mais rápida de encontrar a anotação a copiar.
Blockstudio 7.7 considera $a definido dentro dos templates de blocos, por isso os diagnósticos variable.undefined desaparecem e a anotação se torna opcional. Na versão 7.7, o template com erro acima apresenta quatro erros em vez de seis, e o template corrigido passa sem a linha @var.
Escolha um preset
A instalação do pacote ativa somente a extensão base. O comando canônico executa base, a menos que o projeto selecione outro preset; portanto, adicionar a dependência não ativa, por si só, as camadas mais rigorosas.
| Preset | Adições |
|---|---|
base |
Acesso a campos do template em PHP, Twig e Blade, verificações de tags de bloco, validação de esquema para block.json, field.json, page.json, extensão de JSON, caminhos de db.php, rpc.php e cron.php, e nomes de hooks Settings::get() blockstudio/*. |
theme |
Base, além das raízes do tema e dos cabeçalhos style.css, recursos declarados em block.json em vez de adicionados manualmente à fila, escopo %selector% em style.scss, valores padrão de campos e limites de repetidores. |
extreme-theme |
Tema, além de flags PHPStan rigorosas, chamadas de shell e eval() rejeitadas, gravações $wpdb diretas, escape da saída, Tailwind, JavaScript e verificações de API de Interactivity. |
wordpress-render |
Tema extremo, além de uma verificação de renderização ao vivo fornecida por você como comando. |
Quando nenhuma configuração do projeto é incluída, o comando canônico também executa base e theme no nível PHPStan max; extreme-theme define o próprio max.
Cada diagnóstico de preset tem um identificador blockstudio.* estável, listado na referência de PHPStan.
As camadas de tema e extrema também verificam arquivos PHP. Com um campo sem seu default e um script.js que registra mensagens no console, o mesmo comando relata:
------ -----------------------------------------------------------
Line blockstudio/hero/block.json
------ -----------------------------------------------------------
1 Blockstudio field "subtitle" must define a default value.
🪪 blockstudio.field.default
------ -----------------------------------------------------------
------ ------------------------------------------------------------
Line blockstudio/hero/script.js
------ ------------------------------------------------------------
2 Remove debug output "console.log" from shipped JavaScript.
🪪 blockstudio.javascript.debugOutput
------ ------------------------------------------------------------
Essas verificações são relatadas pelo cache de resultados de PHPStan. Depois de editar apenas um block.json ou um script, um cache aquecido pode relatar [OK] No errors para o estado antigo. Passe --debug após --, o que ignora o cache, antes de confiar em um resultado aprovado para alterações que não sejam de PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Opções do comando e códigos de saída
Os valores da linha de comando substituem os valores correspondentes de blockstudio.json em uma execução. Substituir significa substituir: passar qualquer --exclude descarta o excludePaths configurado; por isso, repita vendor/** ao adicionar um:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Tudo o que vem depois de -- é passado para PHPStan. O wrapper aumenta o limite de memória de PHPStan para 1G, a menos que você informe seu próprio --memory-limit, e monta sua configuração no diretório temporário do sistema, sem criar arquivos gerados no projeto. Ele termina com 0 quando a análise é aprovada, com 1 quando PHPStan relata diagnósticos e com 2 em caso de erros de uso, configuração ou execução.
Execute-o pelo comando canônico em vez de adicionar phpstan/extension-installer. Os presets já incluem a extensão e, com o instalador presente, o mesmo extension.neon é carregado duas vezes: PHPStan para com “This file is included multiple times” antes de analisar qualquer coisa.
Adote-o em um projeto existente
Um projeto analisado pela primeira vez geralmente apresenta problemas. Em vez de reduzir o preset, registre-os em uma linha de base, para que o código novo siga todas as regras:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Inclua a linha de base em uma configuração do projeto e indique seu caminho a phpstan.configuration:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
A próxima execução relata [OK] No errors com os problemas registrados presentes, e qualquer problema novo ainda causa falha. Com os presets base ou theme, também defina level: max em parameters, dentro de phpstan.neon: o comando canônico só define esse nível quando nenhuma configuração do projeto é incluída.
Bloqueie commits com base na análise
Com "githooks": { "commit": true } em blockstudio.json, sincronize o hook gerenciado uma vez após instalar as dependências:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
O comando grava o hook no próprio diretório de Git, aponta core.hooksPath para ele e encadeia qualquer hook de pre-commit configurado anteriormente. O hook executa vendor/bin/blockstudio-phpstan -- --no-progress a partir da raiz do projeto e nada mais: nenhum formatador nem reescrita. O commit do template com erro mostrado anteriormente é interrompido na análise:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Defina commit como false e execute sync novamente, ou execute vendor/bin/blockstudio-githooks remove, para restaurar o caminho anterior do hook.
Somente os arquivos gravados por Blockstudio são excluídos.
Gere o contrato do projeto
A análise informa a um agente o que ele fez de errado depois do fato. Um AGENTS.md informa antes: onde ficam os blocos e as páginas, como os campos chegam aos templates, quais recursos estão ativados e o que o preset selecionado rejeitará.
blockstudio-agents gera esse documento a partir do próprio projeto:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Para o tema deste guia, o arquivo gerado começa assim:
# Blockstudio contract for Acme
## Project
- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.
## What this project contains
- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
Cada linha vem de uma de três fontes. Os arquivos do projeto fornecem o tipo de projeto, as contagens, os diretórios, os namespaces e as linguagens dos templates. blockstudio.json fornece os recursos ativados; por isso, o hook de commit aparece em “Recursos ativados” e vendor/bin/blockstudio-githooks sync aparece em “Comandos” somente porque githooks.commit está definido. O preset selecionado fornece a seção de correção, lida dos arquivos do preset, camada por camada:
The `theme` layer adds:
- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.
Mantenha-o atualizado
O contrato fica desatualizado quando a configuração muda. Depois de ativar Tailwind em blockstudio.json, o modo de verificação detecta:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Ele termina com 1, podendo ser usado como uma etapa de CI junto com a análise. Ao gerar novamente, são adicionados um recurso “Tailwind CSS” e o comando wp bs tailwind compile.
Notas preservadas durante a regeneração
O arquivo termina com uma região de notas. Tudo o que fica entre seus marcadores é preservado byte a byte a cada regeneração; portanto, o conhecimento do projeto que não pode ser obtido dos arquivos deve ficar ali:
## Project notes
Everything above is generated. Text between the markers below is preserved when this file is regenerated.
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
O gerador nunca substitui um arquivo que não tenha criado. Se for executado sobre um AGENTS.md escrito manualmente, ele recusa a operação e termina com 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Para preservar o texto escrito manualmente, copie-o para outro local, execute com --force e cole-o na região de notas. As outras opções são --root, --config, --output e --stdout, que imprime o contrato em vez de gravá-lo.
O que muda em Blockstudio 7.7
O pacote 7.7 mantém os comandos, presets e códigos de saída descritos aqui. Durante a criação deste guia, duas diferenças foram observadas: $a não precisa mais de uma anotação, como descrito na seção de correção, e o contrato gerado descreve de forma mais ampla a validação de tags de blocos, abrangendo elementos HTML mapeados para blocos nas fontes da página e os atributos globais que uma tag pode encaminhar.
Próximas etapas
- PHPStan referência: cada regra, parâmetro predefinido, formato de tipo de campo, teste de renderização ao vivo e identificador de diagnóstico.
- Integração com IA: o índice de documentação para agentes de programação que complementa o contrato do seu projeto.
- Vibe coding com Blockstudio: trabalhando com agentes de programação em um projeto Blockstudio.
- Livro de receitas de padrões de campos: estruturas de campos cujas chaves de template são compreendidas pela análise, incluindo grupos e repetidores.