Pular para o conteúdo

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:

Código
acme/
├── blockstudio/
│   └── hero/
│       ├── block.json
│       └── index.php
├── blockstudio.json
├── composer.json
└── style.css
CSS
/*
Theme Name: Acme
*/

Instale o pacote como uma dependência de desenvolvimento:

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

JSON
{
  "$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:

JSON
{
  "$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:

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

Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 ------ -------------------------------------------------------------------
  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 o block.json ao lado do template, identificou seus campos e verificou que subtitle não está entre eles.
  • offsetAccess.notFound é o próprio PHPStan chegando à mesma conclusão, porque a extensão fornece a $a a estrutura concreta array{heading: string}, derivada de block.json. Cada tipo de campo corresponde a um tipo PHP: text é um string, toggle é um bool, e um repetidor é um array de estruturas de linha.
  • blockstudio.output.unescaped vem da camada extreme-theme. Os valores de atributos impressos devem passar por uma função de escape, como esc_html(), esc_attr(), esc_url() ou wp_kses_post().
  • echo.nonString decorre da chave desconhecida: um deslocamento inexistente não tem tipo string para ser impresso.
  • variable.undefined aparece porque PHPStan encontra um arquivo de template, e não a função de renderização que define $a antes 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:

JSON
{
  "$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
<?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>
Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [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:

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

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

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --root . \
  --exclude 'vendor/**' \
  --exclude 'fixtures/**' \
  --error-format json \
  -- --no-progress
Text
{"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:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Text
 [OK] Baseline generated with 3 errors.

Inclua a linha de base em uma configuração do projeto e indique seu caminho a phpstan.configuration:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "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:

Shell
vendor/bin/blockstudio-githooks sync
Text
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:

Text
 [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:

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

Para o tema deste guia, o arquivo gerado começa assim:

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

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

Shell
vendor/bin/blockstudio-agents --check
Text
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:

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

Text
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