Vai al contenuto

Template verificati con PHPStan e un AGENTS.md generato

Un blocco Blockstudio è composto da due file che devono essere coerenti. Il file block.json dichiara i campi e il template li legge come $a['id']. Durante l’esecuzione, nulla impedisce al template di leggere una chiave rinominata, mai dichiarata o scritta in modo errato. Il risultato è semplicemente una stringa vuota e l’errore emerge quando qualcuno nota un’intestazione vuota su una pagina pubblicata. Lo stesso vale per l’escape dell’output: un echo non sottoposto a escape funziona perfettamente finché il valore di un campo non contiene markup.

Il pacchetto blockstudio/phpstan sposta entrambi i problemi alla fase di analisi. Legge i file block.json, ne ricava i tipi $a e segnala le letture nei template che non corrispondono. Le preimpostazioni facoltative aggiungono regole sulla struttura del tema, sull’escape e controlli JavaScript e Tailwind. Lo stesso pacchetto include due componenti aggiuntivi: un hook pre-commit gestito che esegue l’analisi e un generatore che crea un file AGENTS.md sul progetto per gli agenti di programmazione.

Questa guida crea un piccolo tema, altera intenzionalmente uno dei suoi template, esamina l’output dell’analisi, lo corregge e infine configura il blocco dei commit e il contratto per l’agente.

Configurare il tema

Iniziate con una cartella del tema contenente un’intestazione style.css, un composer.json e un blocco:

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

Installate il pacchetto come dipendenza di sviluppo:

Shell
composer require --dev blockstudio/phpstan

Installa PHPStan e gli stub WordPress da szepeviktor/phpstan-wordpress e aggiunge tre eseguibili in vendor/bin: blockstudio-phpstan, blockstudio-githooks e blockstudio-agents.

Poi indicate all’analisi cosa eseguire. Le impostazioni predefinite per l’intero progetto si trovano nell’oggetto phpstan di blockstudio.json, così le esecuzioni interattive, la CI e l’hook di commit leggono tutte le stesse impostazioni:

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

extreme-theme è la più rigorosa delle tre preimpostazioni statiche. La tabella più avanti spiega cosa aggiunge ciascuna. excludePaths esclude i file di Composer stesso dalla scansione Blockstudio e dall’analisi PHP.

Alterare intenzionalmente un template

Il blocco hero dichiara un solo campo:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" }
    ]
  }
}

Il template legge correttamente quel campo, poi ne legge uno subtitle mai dichiarato nel blocco e lo stampa senza applicare l’escape:

PHP
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
</section>

Nell’editor e nel frontend, questo genera un paragrafo vuoto senza errori. Eseguite invece l’analisi:

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

Il comando termina con 1. Ecco la diagnostica, dalla più specifica alla meno specifica:

  • blockstudio.field è la regola del template. Ha trovato block.json accanto al template, ne ha risolto i campi e ha rilevato che subtitle non è tra questi.
  • offsetAccess.notFound arriva alla stessa conclusione tramite PHPStan stesso, perché l’estensione attribuisce a $a la struttura concreta array{heading: string} dedotta da block.json. A ogni tipo di campo corrisponde un tipo PHP: text è un string, toggle è un bool, mentre un repeater è un array di strutture di riga.
  • blockstudio.output.unescaped proviene dal livello extreme-theme. I valori degli attributi stampati devono passare attraverso una funzione di escape, come esc_html(), esc_attr(), esc_url() o wp_kses_post().
  • echo.nonString deriva dalla chiave sconosciuta: un offset inesistente non ha un tipo stringa da stampare.
  • variable.undefined compare perché PHPStan rileva un file template, non la funzione di rendering che definisce $a prima di includerlo. La sezione sulla correzione spiega come risolvere il problema.

Correggere il problema

Stabilite se subtitle è un campo effettivo. In questo caso sì, quindi dichiaratelo e aggiungete un default, richiesto dal livello del tema per ogni 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": "" }
    ]
  }
}

Applicate l’escape all’output e dichiarate $a con la struttura dedotta dall’estensione:

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

Scrivete l’annotazione usando la struttura esatta. Il comando canonico esegue PHPStan al livello max, dove una dichiarazione @var array<string, mixed> $a meno rigorosa viene rifiutata con varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). Nella versione 7.6, inoltre, ogni campo viene esteso a mixed, quindi ogni chiamata a esc_html() segnala argument.type. Il messaggio varTag.nativeType mostra la struttura dedotta, perciò è anche il modo più rapido per individuare l’annotazione da copiare.

Blockstudio 7.7 considera $a definito nei template dei blocchi, quindi le diagnostiche variable.undefined scompaiono e l’annotazione diventa facoltativa. Con la versione 7.7, il template errato qui sopra segnala quattro errori invece di sei e il template corretto passa senza la riga @var.

Scegliere una preimpostazione

L’installazione del pacchetto abilita solo l’estensione di base. Il comando canonico esegue base, a meno che il progetto non scelga un’altra preimpostazione; quindi aggiungere la dipendenza non attiva da solo i livelli più rigorosi.

Preimpostazione Aggiunge
base Accesso ai campi del template in PHP, Twig e Blade, controlli dei tag dei blocchi, convalida dello schema per block.json, field.json, page.json, JSON dell’estensione, percorsi db.php, rpc.php e cron.php, nonché nomi degli hook Settings::get(), blockstudio/*.
theme Base, più radici del tema e intestazioni style.css, risorse dichiarate in block.json invece che accodate manualmente, limitazione dell’ambito di %selector% in style.scss, valori predefiniti dei campi e limiti dei repeater.
extreme-theme Tema, più flag PHPStan rigorosi, chiamate shell e eval() rifiutate, scritture $wpdb dirette, escape dell’output, Tailwind, JavaScript e controlli API di Interactivity.
wordpress-render Tema estremo, più un controllo del rendering reale fornito da voi come comando.

Quando non è inclusa alcuna configurazione di progetto, il comando canonico esegue base e theme anche al livello PHPStan max; extreme-theme imposta autonomamente max. Ogni diagnostica predefinita ha un identificatore blockstudio.* stabile, elencato nel riferimento PHPStan.

I livelli del tema e estremo esaminano anche i file PHP. Se manca il default di un campo e c’è un script.js che scrive nella console, lo stesso comando segnala:

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

Questi controlli vengono segnalati tramite la cache dei risultati di PHPStan. Se modificate solo un block.json o uno script, una cache già popolata può segnalare [OK] No errors relativo allo stato precedente. Dopo --, passate --debug per ignorare la cache prima di considerare superata un’esecuzione per modifiche che non riguardano PHP:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --debug

Opzioni del comando e codici di uscita

I valori della riga di comando sostituiscono, per una singola esecuzione, i valori blockstudio.json corrispondenti. La sostituzione è completa: passando un qualsiasi --exclude si elimina excludePaths configurato, quindi quando ne aggiungete uno ripetete vendor/**:

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":[]}

Tutto ciò che segue -- viene passato a PHPStan. Il wrapper aumenta il limite di memoria di PHPStan a 1G, a meno che non passiate un vostro --memory-limit, e compone la configurazione nella directory temporanea di sistema, quindi nessun file generato finisce nel progetto. Termina con 0 se l’analisi riesce, con 1 se PHPStan rileva diagnostiche e con 2 in caso di errori di utilizzo, configurazione o esecuzione.

Eseguitelo con il comando canonico, invece di aggiungere phpstan/extension-installer. Le preimpostazioni includono già l’estensione e, se l’installer è presente, lo stesso extension.neon viene caricato due volte: PHPStan si interrompe con “This file is included multiple times” prima di analizzare qualsiasi cosa.

Adottarlo in un progetto esistente

La prima analisi di un progetto di solito rileva problemi. Invece di abbassare la preimpostazione, registrateli in una baseline, così il nuovo codice dovrà rispettare tutte le regole:

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

Includete la baseline nella configurazione del progetto e indicatela a phpstan.configuration:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"],
    "configuration": "phpstan.neon"
  }
}

L’esecuzione successiva segnala [OK] No errors tenendo conto dei problemi registrati, mentre ogni nuovo problema continua a farla fallire. Con la preimpostazione base o theme, impostate anche level: max in parameters dentro phpstan.neon: il comando canonico imposta autonomamente quel livello solo se non è inclusa una configurazione di progetto.

Bloccare i commit in base all’analisi

Con "githooks": { "commit": true } in blockstudio.json, sincronizzate una volta l’hook gestito dopo aver installato le dipendenze:

Shell
vendor/bin/blockstudio-githooks sync
Text
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit

Il comando scrive l’hook nella directory di Git stesso, imposta core.hooksPath perché lo utilizzi e concatena l’eventuale hook pre-commit configurato in precedenza. L’hook esegue solo vendor/bin/blockstudio-phpstan -- --no-progress dalla radice del progetto, senza formattatori né riscritture. Il commit del template errato visto prima si interrompe durante l’analisi:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Impostate commit su false e rieseguite sync, oppure eseguite vendor/bin/blockstudio-githooks remove per ripristinare il percorso dell’hook precedente. Vengono eliminati solo i file scritti da Blockstudio.

Generare il contratto del progetto

L’analisi dice a un agente cosa ha sbagliato dopo il fatto. Un AGENTS.md lo informa in anticipo: dove si trovano blocchi e pagine, come arrivano i campi ai template, quali funzionalità sono abilitate e cosa rifiuterà la preimpostazione selezionata. blockstudio-agents genera questo documento a partire dal progetto stesso:

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

Per il tema di questa guida, il file generato inizia così:

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.

Ogni riga proviene da una di tre fonti. I file del progetto forniscono il tipo di progetto, i conteggi, le directory, gli spazi dei nomi e i linguaggi dei template. blockstudio.json fornisce le funzionalità abilitate, quindi l’hook di commit compare in “Enabled features” e vendor/bin/blockstudio-githooks sync in “Commands” solo perché è impostato githooks.commit. La sezione sulla correttezza dipende dalla preimpostazione selezionata e viene letta dai file delle preimpostazioni, livello per livello:

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.

Mantenere aggiornato il documento

Il contratto diventa obsoleto quando cambia la configurazione. Dopo aver abilitato Tailwind in blockstudio.json, la modalità di controllo se ne accorge:

Shell
vendor/bin/blockstudio-agents --check
Text
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.

Termina con 1, quindi può essere usato come passaggio CI accanto all’analisi. Rigenerando il documento, vengono aggiunti una voce di funzionalità “Tailwind CSS” e il comando wp bs tailwind compile.

Note che vengono conservate dopo la rigenerazione

Il file termina con una sezione per le note. Tutto ciò che si trova tra i relativi marcatori viene conservato byte per byte a ogni rigenerazione, quindi inserite lì le informazioni sul progetto che non si possono ricavare dai file:

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

Il generatore non sostituisce mai un file che non ha creato. Se lo eseguite su un AGENTS.md scritto manualmente, si rifiuta di procedere e termina con 2:

Text
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.

Per conservare il testo scritto manualmente, copiatelo altrove, eseguite il comando con --force e incollatelo nella sezione delle note. Le altre opzioni sono --root, --config, --output e --stdout, che stampa il contratto invece di scriverlo.

Novità nella versione Blockstudio 7.7

Il pacchetto 7.7 mantiene i comandi, le preimpostazioni e i codici di uscita descritti qui. Durante la preparazione di questa guida con la versione 7.7 sono emerse due differenze: $a non richiede più un’annotazione, come descritto nella sezione sulla correzione, e il contratto generato descrive più ampiamente la convalida dei tag dei blocchi, includendo gli elementi HTML associati ai blocchi nelle fonti delle pagine e gli attributi globali che un tag può trasmettere.

Passaggi successivi

  • PHPStanriferimento: ogni regola, parametro preimpostato, struttura dei tipi di campo, probe di rendering in tempo reale e identificatore diagnostico.
  • Integrazione con l’IA: l’indice della documentazione per gli agenti di programmazione, che integra il contratto del progetto.
  • Programmare con Blockstudio: lavorare con agenti di programmazione su un progetto Blockstudio.
  • Ricettario dei modelli di campo: strutture di campo di cui l’analisi comprende le chiavi dei template, inclusi gruppi e ripetitori.