Hoppa till innehåll

Kontrollerade mallar med PHPStan och en genererad AGENTS.md

Ett Blockstudio-block består av två filer som måste stämma överens. block.json deklarerar fälten, och mallen läser dem som $a['id']. Inget hindrar mallen från att läsa en nyckel som har bytt namn, aldrig deklarerats eller stavats fel. Den renderar bara en tom sträng, och misstaget upptäcks först när någon ser en tom rubrik på en publicerad sida. Detsamma gäller output-escaping: oescapad echo fungerar utmärkt tills ett fältvärde innehåller markup.

Paketet blockstudio/phpstan flyttar båda problemen till analystillfället. Det läser dina block.json-filer, härleder typer för $a från dem och rapporterar malläsningar som inte stämmer. De valfria förinställningarna lägger till regler för temastruktur, escaping samt kontroller av JavaScript och Tailwind. Samma paket innehåller två tillägg: en hanterad pre-commit-hook som kör analysen och en generator som skriver ett AGENTS.md med en beskrivning av projektet för kodningsagenter.

Den här guiden bygger ett litet tema, bryter avsiktligt en av dess mallar, läser analysutdata, åtgärdar felet och kopplar sedan in commit-kontrollen och agentkontraktet.

Konfigurera temat

Börja med en temamapp som har ett style.css-huvud, ett composer.json och ett block:

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

Installera paketet som ett utvecklingsberoende:

Shell
composer require --dev blockstudio/phpstan

Det hämtar in PHPStan och stubbarna för WordPress från szepeviktor/phpstan-wordpress och installerar tre körbara filer i vendor/bin: blockstudio-phpstan, blockstudio-githooks och blockstudio-agents.

Ange sedan vad analysen ska köra. Projektgemensamma standardvärden finns i objektet phpstan i blockstudio.json, så interaktiva körningar, CI och commit-hooken använder samma inställningar:

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

extreme-theme är den striktaste av de tre statiska förinställningarna. Tabellen längre ned förklarar vad varje förinställning lägger till. excludePaths håller Composers egna filer utanför genomsökningen med Blockstudio och analysen av PHP.

Bryt en mall avsiktligt

Hero-blocket deklarerar ett enda fält:

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

Mallen läser fältet korrekt och läser sedan ett subtitle som blocket aldrig deklarerade och skriver ut det utan escaping:

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

I redigeraren och i frontend renderas detta som ett tomt stycke utan fel. Kör analysen i stället:

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

Kommandot avslutas med 1. Läs diagnostikmeddelandena med början från det mest specifika:

  • blockstudio.field är mallregeln. Den hittade block.json bredvid mallen, slog upp dess fält och konstaterade att subtitle inte finns bland dem.
  • offsetAccess.notFound drar samma slutsats om PHPStan, eftersom tillägget ger $a den konkreta formen array{heading: string}, härledd från block.json. Varje fälttyp motsvarar en PHP-typ: text är en string, toggle en bool och en repeater en array av radformer.
  • blockstudio.output.unescaped kommer från lagret extreme-theme. Ekoade attributvärden måste gå genom en escaping-funktion som esc_html(), esc_attr(), esc_url() eller wp_kses_post().
  • echo.nonString följer av den okända nyckeln: ett offset som inte finns har ingen strängtyp att skriva ut.
  • variable.undefined visas eftersom PHPStan ser en mallfil, inte renderingsfunktionen som definierar $a innan den inkluderas. Avsnittet om åtgärden tar upp det.

Åtgärda felet

Avgör om subtitle är ett riktigt fält. Här är det det, så deklarera det med en default, eftersom temalagret kräver en för varje fält:

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

Escapa utdata och deklarera $a med den form som tillägget härleder:

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

Skriv annoteringen med exakt den här formen. Det kanoniska kommandot kör PHPStan på nivå max, där en mindre strikt @var array<string, mixed> $a avvisas med varTag.nativeType (“PHPDoc-tagg @var med typen array<string, mixed> är inte en undertyp av den inbyggda typen array{heading: string, subtitle: string}”). I 7.6 breddas dessutom varje fält till mixed, så varje anrop till esc_html() rapporterar argument.type. Meddelandet varTag.nativeType skriver ut den härledda formen och är därför också det snabbaste sättet att hitta annoteringen att kopiera.

I 7.7 behandlar Blockstudio $a som definierat i blockmallar, så diagnostikmeddelandena från variable.undefined försvinner och annoteringen blir valfri. Med 7.7 rapporterar den trasiga mallen ovan fyra fel i stället för sex, och den åtgärdade mallen klarar kontrollen utan raden @var.

Välj en förinställning

När paketet installeras aktiveras bara bastillägget. Det kanoniska kommandot kör base om inte ett projekt väljer en annan förinställning, så beroendet aktiverar inte de striktare lagren i sig.

Förinställning Innehåller
base Åtkomst till mallfält i PHP, Twig och Blade, kontroller av blocktaggar, schemavalidering för block.json, field.json, page.json, tilläggets JSON, db.php, rpc.php och sökvägarna cron.php, Settings::get() samt hooknamn för blockstudio/*.
theme Basen samt temarötter och style.css-huvuden, resurser deklarerade i block.json i stället för att läggas till manuellt, avgränsning av %selector% i style.scss, fältstandardvärden och gränser för repeaters.
extreme-theme Tema samt strikta flaggor för PHPStan, avvisade anrop till shell och eval(), råa skrivningar med $wpdb, output-escaping samt kontroller av Tailwind, JavaScript och Interactivity API.
wordpress-render Extremt tema samt en live-renderingskontroll som du tillhandahåller som ett kommando.

När ingen projektkonfiguration ingår kör det kanoniska kommandot även base och theme på nivån PHPStan max; extreme-theme ställer själv in max. Varje förinställd diagnostik har en stabil identifierare blockstudio.*, som finns i referensen PHPStan.

Tema- och extremalagren granskar även PHP-filer. Om ett fält saknar sitt default och en script.js loggar till konsolen rapporterar samma kommando:

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

Dessa kontroller rapporteras via resultatcachen i PHPStan. Om du bara har redigerat en block.json eller ett skript kan en varm cache rapportera [OK] No errors för det gamla tillståndet. Skicka med --debug efter --, vilket kringgår cachen, innan du litar på ett godkänt resultat för ändringar som inte gäller PHP:

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

Kommandoalternativ och avslutningskoder

Kommandoradsvärden ersätter motsvarande värden för blockstudio.json vid en körning. Ersätta betyder ersätta: om du anger något --exclude försvinner det konfigurerade excludePaths, så upprepa vendor/** när du lägger till ett:

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

Allt efter -- skickas till PHPStan. Wrappern höjer minnesgränsen för PHPStan till 1G om du inte anger ett eget --memory-limit, och sätter samman konfigurationen i systemets temporära katalog så att inga genererade filer hamnar i projektet. Kommandot avslutas med 0 när analysen godkänns, 1 när PHPStan rapporterar diagnostik och 2 vid fel i användning, konfiguration eller körning.

Kör det via det kanoniska kommandot i stället för att lägga till phpstan/extension-installer. Förinställningarna innehåller redan tillägget, och när installeraren finns laddas samma extension.neon två gånger: PHPStan avbryts med ”Den här filen inkluderas flera gånger” innan någon analys har gjorts.

Inför det i ett befintligt projekt

Ett projekt som analyseras för första gången har vanligtvis anmärkningar. Sänk inte förinställningen; registrera dem i en baslinje så att ny kod måste följa de fullständiga reglerna:

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

Inkludera baslinjen från en projektkonfiguration och ange den för phpstan.configuration:

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

Nästa körning rapporterar [OK] No errors med de registrerade anmärkningarna på plats, medan allt nytt fortfarande leder till fel. Med förinställningen base eller theme ska du även ange level: max under parameters i phpstan.neon: det kanoniska kommandot ställer bara in den nivån när ingen projektkonfiguration ingår.

Stoppa commits vid analysfel

Med "githooks": { "commit": true } i blockstudio.json synkroniserar du den hanterade hooken en gång efter att beroendena har installerats:

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

Kommandot skriver hooken i den egna katalogen för Git, pekar core.hooksPath på den och kedjar ihop den med eventuell pre-commit-hook som var konfigurerad tidigare. Hooken kör vendor/bin/blockstudio-phpstan -- --no-progress från projektroten och inget annat: ingen formatterare och inga omskrivningar. Om du försöker committa den trasiga mallen från tidigare stoppas det vid analysen:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Ställ in commit på false och kör sync igen, eller kör vendor/bin/blockstudio-githooks remove för att återställa den tidigare sökvägen till hooken. Bara filer som Blockstudio har skrivit tas bort.

Generera projektkontraktet

Analysen talar om för en agent vad den gjorde fel i efterhand. Ett AGENTS.md informerar den i förväg: var block och sidor finns, hur fält når mallar, vilka funktioner som är aktiverade och vad den valda förinställningen kommer att avvisa. blockstudio-agents genererar dokumentet från själva projektet:

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

För temat i den här guiden börjar den genererade filen så här:

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.

Varje rad hämtas från en av tre källor. Projektets filer anger projekttyp, antal, kataloger, namnrymder och mallspråk. blockstudio.json anger aktiverade funktioner, så commit-hooken visas under ”Aktiverade funktioner” och vendor/bin/blockstudio-githooks sync under ”Kommandon” enbart för att githooks.commit är inställt. Den valda förinställningen anger avsnittet om korrekthet, som hämtas från förinställningsfilerna lager för lager:

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.

Håll det uppdaterat

Kontraktet blir inaktuellt när konfigurationen ändras. När Tailwind har aktiverats i blockstudio.json upptäcker kontrolläget det:

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

Det avslutas med 1, vilket gör att det kan användas som ett CI-steg bredvid analysen. Om du genererar på nytt läggs en funktionspost till med namnet ”Tailwind CSS” samt kommandot wp bs tailwind compile.

Anteckningar som bevaras vid generering

Filen avslutas med ett anteckningsområde. Allt mellan markörerna bevaras byte för byte vid varje ny generering, så projektkunskap som inte går att härleda från filer hör hemma där:

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

Generatorn ersätter aldrig en fil som den inte själv har skrivit. Om du kör den mot ett handskrivet AGENTS.md vägrar den och avslutas med 2:

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

Om du vill behålla handskriven text kopierar du undan den, kör med --force och klistrar in den i anteckningsområdet. De andra alternativen är --root, --config och --output, samt --stdout som skriver ut kontraktet i stället för att skriva det till en fil.

Vad som ändras i Blockstudio 7.7

Paketet 7.7 har kvar kommandona, förinställningarna och avslutningskoderna som beskrivs här. Två skillnader framkom när guiden togs fram med den versionen: $a behöver inte längre en annotering, som beskrivs i avsnittet om åtgärden, och det genererade kontraktet beskriver validering av blocktaggar bredare. Det omfattar HTML-element som kopplas till block i sidkällor samt de globala attribut som en tagg kan vidarebefordra.

Nästa steg

  • PHPStan-referens: varje regel, förinställd parameter, fälttyp och struktur, live-renderingskontroll och diagnostisk identifierare.
  • AI-integration: dokumentationsindexet för kodningsagenter som kompletterar projektets kontrakt.
  • Vibekodning med Blockstudio: arbeta med kodningsagenter i ett Blockstudio-projekt.
  • Kokbok med fältmönster: fältstrukturer vars mallnycklar analysen förstår, inklusive grupper och upprepningsfält.