Gå til indhold

Kontrollerede skabeloner med PHPStan og en genereret AGENTS.md

En Blockstudio-blok består af to filer, der skal stemme overens. block.json erklærer felterne, og skabelonen læser dem som $a['id']. Intet ved runtime forhindrer skabelonen i at læse en nøgle, der er omdøbt, aldrig erklæret eller stavet forkert. Den gengiver blot en tom streng, og fejlen opdages først, når nogen bemærker en tom overskrift på en aktiv side. Det samme gælder output-escaping: Et echo uden escaping fungerer perfekt, indtil en feltværdi indeholder markup.

Pakken blockstudio/phpstan flytter begge problemer til analysetidspunktet. Den læser dine block.json-filer, bestemmer typerne for $a ud fra dem og rapporterer skabelonlæsninger, der ikke stemmer overens. De valgfri forudindstillinger tilføjer regler for temastruktur, escaping samt kontroller af JavaScript og Tailwind. Pakken indeholder også to tilføjelser: en administreret pre-commit-hook, der kører analysen, og en generator, der skriver et AGENTS.md, som beskriver dit projekt for kodeagenter.

Denne vejledning opretter et lille tema, ødelægger med vilje en af dets skabeloner, gennemgår analysens output, retter skabelonen og konfigurerer derefter commit-kontrollen og agentkontrakten.

Konfigurer temaet

Begynd med en temamappe, der har en header for style.css, en composer.json og én blok:

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

Installer pakken som en udviklingsafhængighed:

Shell
composer require --dev blockstudio/phpstan

Den medtager PHPStan og WordPress-stubbene fra szepeviktor/phpstan-wordpress og installerer tre eksekverbare filer i vendor/bin: blockstudio-phpstan, blockstudio-githooks og blockstudio-agents.

Angiv derefter, hvad analysen skal køre. Projektets standardindstillinger placeres i objektet phpstan i blockstudio.json, så interaktive kørsler, CI og commit-hooken bruger de samme indstillinger:

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

extreme-theme er den strengeste af de tre statiske forudindstillinger. Tabellen nedenfor beskriver, hvad hver af dem tilføjer. excludePaths holder Composers egne filer ude af scanningen Blockstudio og analysen PHP.

Ødelæg en skabelon med vilje

Hero-blokken erklærer ét felt:

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

Skabelonen læser feltet korrekt og læser derefter et subtitle, som blokken aldrig har erklæret, og udskriver det uden escaping:

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

I editoren og på frontend gengiver dette et tomt afsnit uden fejl. Kør analysen i stedet:

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

Kommandoen afsluttes med 1. Her er diagnostikken gennemgået fra den mest specifikke til den mindst specifikke:

  • blockstudio.field er skabelonreglen. Den fandt block.json ved siden af skabelonen, slog felterne op og konstaterede, at subtitle ikke er et af dem.
  • offsetAccess.notFound er PHPStan selv, der når frem til samme konklusion, fordi udvidelsen giver $a den konkrete form array{heading: string}, der er udledt af block.json. Hver felttype svarer til en PHP-type: text er en string, toggle en bool, og en repeater er en array med rækkernes former.
  • blockstudio.output.unescaped kommer fra laget extreme-theme. Udskrevne attributværdier skal sendes gennem en escaping-funktion såsom esc_html(), esc_attr(), esc_url() eller wp_kses_post().
  • echo.nonString følger af den ukendte nøgle: Et offset, der ikke findes, har ingen strengtype, der kan udskrives.
  • variable.undefined vises, fordi PHPStan ser en skabelonfil, ikke den renderfunktion, der definerer $a, før den inkluderes. Afsnittet om rettelser gennemgår dette.

Ret det

Afgør, om subtitle er et reelt felt. Her er svaret ja, så erklær det med en default, da temalaget kræver en for hvert felt:

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

Brug escaping på outputtet, og erklær $a med den form, som udvidelsen udleder:

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 den præcise form. Den kanoniske kommando kører PHPStan på niveau max, hvor en løsere @var array<string, mixed> $a afvises med varTag.nativeType (“PHPDoc-tagget @var med typen array<string, mixed> er ikke en undertype af den native type array{heading: string, subtitle: string}”). I 7.6 udvider den også alle felter til mixed, så hvert kald af esc_html() rapporterer argument.type. Meddelelsen varTag.nativeType viser den udledte form, så det er også den hurtigste måde at finde annoteringen, du kan kopiere.

Blockstudio 7.7 behandler $a som defineret i blokskabeloner, så diagnostikken variable.undefined forsvinder, og annoteringen bliver valgfri. Med 7.7 rapporterer den ødelagte skabelon ovenfor fire fejl i stedet for seks, og den rettede skabelon godkendes uden linjen @var.

Vælg en forudindstilling

Installation af pakken aktiverer kun basisudvidelsen. Den kanoniske kommando kører base, medmindre projektet vælger en anden forudindstilling, så tilføjelsen af afhængigheden aktiverer ikke i sig selv de strengere lag.

Forudindstilling Tilføjer
base Feltadgang i skabeloner med PHP, Twig og Blade, kontroller af bloktags, skemavalidering af block.json, field.json, page.json, udvidelserne JSON, db.php, rpc.php og cron.php, stierne Settings::get() og hooknavnene blockstudio/*.
theme Base samt temarødder og headers for style.css, aktiver erklæret i block.json i stedet for at blive tilføjet manuelt, afgrænsning af %selector% i style.scss, feltstandarder og grænser for repeatere.
extreme-theme Tema samt strenge flag for PHPStan, afviste shell- og eval()-kald, rå $wpdb-skrivninger, output-escaping samt kontroller af Tailwind, JavaScript og Interactivity API.
wordpress-render Extreme-tema samt en live-renderprobe, som du angiver som en kommando.

Når projektkonfiguration ikke er inkluderet, kører den kanoniske kommando også base og theme på niveau PHPStan max; extreme-theme indstiller selv max. Hver diagnostik fra en forudindstilling har en stabil blockstudio.*-identifikator, som findes i referencen for PHPStan.

Tema- og extreme-lagene ser ud over PHP-filer. Når et felt mangler sin default, og en script.js logger i konsollen, rapporterer den samme 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
 ------ ------------------------------------------------------------

Disse kontroller rapporteres via resultatcachen i PHPStan. Efter du kun har redigeret en block.json eller et script, kan en varm cache rapportere [OK] No errors for den gamle tilstand. Angiv --debug efter --, hvilket omgår cachen, før du stoler på et grønt resultat for ændringer, der ikke vedrører PHP:

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

Kommandoindstillinger og afslutningskoder

Kommandolinjeværdier erstatter de tilsvarende blockstudio.json-værdier for én kørsel. De erstatter dem helt: Hvis du angiver en --exclude, fjernes den konfigurerede excludePaths, så gentag vendor/**, når du tilføjer én:

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

Alt efter -- sendes til PHPStan. Wrapperen hæver hukommelsesgrænsen for PHPStan til 1G, medmindre du angiver din egen --memory-limit, og sammensætter konfigurationen i systemets midlertidige mappe, så ingen genereret fil placeres i projektet. Den afsluttes med 0, når analysen godkendes, 1, når PHPStan rapporterer diagnostik, og 2 ved fejl i brug, konfiguration eller udførelse.

Kør den via den kanoniske kommando i stedet for at tilføje phpstan/extension-installer. Forudindstillingerne inkluderer allerede udvidelsen, og med installeringsprogrammet til stede indlæses samme extension.neon to gange: PHPStan stopper med “This file is included multiple times”, før noget analyseres.

Tag den i brug i et eksisterende projekt

Et projekt, der analyseres for første gang, har som regel fund. I stedet for at sænke forudindstillingen kan du registrere dem i en baseline, så ny kode stadig skal overholde alle regler:

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

Inkluder baselinen fra en projektkonfiguration, og peg phpstan.configuration på den:

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

Den næste kørsel rapporterer [OK] No errors med de registrerede fund på plads, mens alt nyt stadig medfører fejl. Med forudindstillingen base eller theme skal du også indstille level: max under parameters i phpstan.neon: Den kanoniske kommando indstiller kun selv dette niveau, når der ikke er inkluderet nogen projektkonfiguration.

Blokér commits på analysen

Når "githooks": { "commit": true } er i blockstudio.json, skal du synkronisere den administrerede hook én gang efter installation af afhængigheder:

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

Kommandoen skriver hooken i sin egen mappe for Git, peger core.hooksPath på den og kæder den sammen med den pre-commit-hook, der allerede var konfigureret. Hooken kører vendor/bin/blockstudio-phpstan -- --no-progress fra projektets rodmappe og intet andet: ingen formattering og ingen omskrivninger. Hvis du forsøger at committe den ødelagte skabelon fra før, stopper analysen committen:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Indstil commit til false, og kør sync igen, eller kør vendor/bin/blockstudio-githooks remove for at gendanne den tidligere hooksti. Kun filer skrevet af Blockstudio slettes.

Generér projektkontrakten

Analysen fortæller en agent bagefter, hvad den gjorde forkert. En AGENTS.md fortæller det på forhånd, hvor blokke og sider ligger, hvordan felter når skabelonerne, hvilke funktioner der er aktiveret, og hvad den valgte forudindstilling vil afvise. blockstudio-agents genererer dokumentet ud fra selve projektet:

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

For temaet i denne vejledning begynder den genererede fil sådan:

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.

Hver linje kommer fra ét af tre steder. Projektets filer angiver projekttypen, antal, mapper, navnerum og skabelonsprog. blockstudio.json angiver de aktiverede funktioner, så commit-hooken vises under “Aktiverede funktioner” og vendor/bin/blockstudio-githooks sync under “Kommandoer”, kun fordi githooks.commit er indstillet. Den valgte forudindstilling bestemmer afsnittet om korrekthed, som læses fra forudindstillingens filer lag for lag:

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.

Hold den opdateret

Kontrakten bliver forældet, når konfigurationen ændres. Når du aktiverer Tailwind i blockstudio.json, opdager kontroltilstanden 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.

Den afsluttes med 1, så den kan bruges som et CI-trin ved siden af analysen. En ny generering tilføjer et “Tailwind CSS”-funktionspunkt og kommandoen wp bs tailwind compile.

Noter, der bevares ved generering

Filen slutter med et noteområde. Alt mellem dets markører bevares byte for byte ved hver generering, så projektviden, der ikke kan udledes af filer, hører hjemme der:

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

Generatoren erstatter aldrig en fil, den ikke selv har skrevet. Hvis du kører den mod et håndskrevet AGENTS.md, afviser den det og afsluttes med 2:

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

Hvis du vil beholde håndskrevet tekst, skal du kopiere den til side, køre med --force og indsætte teksten i noteområdet. De øvrige indstillinger er --root, --config, --output og --stdout, som udskriver kontrakten i stedet for at skrive den til en fil.

Ændringer i Blockstudio 7.7

Pakken 7.7 bevarer de kommandoer, forudindstillinger og afslutningskoder, der beskrives her. Under udarbejdelsen af denne vejledning med pakken blev der konstateret to forskelle: $a behøver ikke længere en annotering, som beskrevet i afsnittet om rettelser, og den genererede kontrakt beskriver validering af bloktags mere bredt. Den omfatter elementer af typen HTML, der er knyttet til blokke i sidekilder, samt de globale attributter, et tag kan videresende.

Næste trin

  • PHPStan-reference: hver regel, forudindstillet parameter, felttypestruktur, live-renderingsprobe og diagnosticerings-id.
  • AI-integration: dokumentationsindekset for kodeagenter, der supplerer din projektkontrakt.
  • Vibecoding med Blockstudio: samarbejde med kodeagenter om et Blockstudio-projekt.
  • Field Patterns Cookbook: feltstrukturer, hvis skabelonnøgler analysen forstår, herunder grupper og repeatere.