Treci la conținut

Șabloane verificate cu PHPStan și un AGENTS.md generat

Un bloc Blockstudio constă din două fișiere care trebuie să corespundă. block.json declară câmpurile, iar șablonul le citește ca $a['id']. Nimic în timpul execuției nu împiedică șablonul să citească o cheie care a fost redenumită, nu a fost declarată sau a fost scrisă greșit. Pur și simplu afișează un șir gol, iar greșeala este observată abia când cineva remarcă un titlu gol pe o pagină publicată. Același lucru este valabil și pentru escaparea ieșirii: un echo neescapat funcționează perfect până când valoarea unui câmp conține marcaj.

Pachetul blockstudio/phpstan rezolvă ambele probleme în etapa de analiză. Citește fișierele block.json, deduce tipurile pentru $a din ele și raportează accesările din șabloane care nu corespund. Presetările opționale adaugă reguli de structură a temei, escapare și verificări pentru JavaScript și Tailwind. Pachetul include și două instrumente auxiliare: un hook gestionat de pre-commit care rulează analiza și un generator care scrie un AGENTS.md ce descrie proiectul pentru agenții de programare.

Acest ghid construiește o temă mică, defectează intenționat unul dintre șabloanele ei, examinează rezultatul analizei, îl remediază, apoi configurează blocarea commit-urilor și contractul pentru agent.

Configurarea temei

Începeți cu un director de temă care conține un antet style.css, un composer.json și un bloc:

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

Instalați pachetul ca dependență de dezvoltare:

Shell
composer require --dev blockstudio/phpstan

Acesta instalează PHPStan și stuburile WordPress din szepeviktor/phpstan-wordpress, precum și trei executabile în vendor/bin: blockstudio-phpstan, blockstudio-githooks și blockstudio-agents.

Apoi indicați analizei ce să ruleze. Valorile implicite pentru întregul proiect se află în obiectul phpstan din blockstudio.json, astfel încât execuțiile interactive, CI și hook-ul de commit citesc aceleași setări:

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

extreme-theme este cea mai strictă dintre cele trei presetări statice. Tabelul de mai jos explică ce adaugă fiecare. excludePaths exclude propriile fișiere ale Composer din scanarea Blockstudio și din analiza PHP.

Defectarea intenționată a unui șablon

Blocul principal declară un singur câmp:

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

Șablonul citește corect acel câmp, apoi citește un subtitle pe care blocul nu l-a declarat și îl afișează fără escapare:

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

În editor și pe frontend, se afișează un paragraf gol și nicio eroare. Rulați în schimb analiza:

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

Comanda se încheie cu 1. Iată diagnosticele, de la cele mai specifice la cele mai generale:

  • blockstudio.field este regula pentru șabloane. A găsit block.json lângă șablon, a rezolvat câmpurile acestuia și subtitle nu se află printre ele.
  • offsetAccess.notFound este PHPStan însuși care ajunge la aceeași concluzie, deoarece extensia îi oferă lui $a forma concretă array{heading: string} dedusă din block.json. Fiecare tip de câmp corespunde unui tip PHP: text este un string, toggle este un bool, iar un repeater este o matrice de forme pentru rânduri.
  • blockstudio.output.unescaped provine din stratul extreme-theme. Valorile atributelor afișate trebuie să treacă printr-o funcție de escapare, precum esc_html(), esc_attr(), esc_url() sau wp_kses_post().
  • echo.nonString este consecința cheii necunoscute: un offset care nu există nu are un tip șir care să poată fi afișat.
  • variable.undefined apare deoarece PHPStan vede un fișier șablon, nu funcția de randare care definește $a înainte de a-l include. Secțiunea de remediere explică soluția.

Remedierea

Stabiliți dacă subtitle este un câmp real. Aici este, așa că declarați-l cu un default, deoarece stratul temei impune unul pentru fiecare câmp:

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ți ieșirea și declarați $a cu forma dedusă de extensie:

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

Scrieți adnotarea folosind forma exactă. Comanda canonică rulează PHPStan la nivelul max, unde un @var array<string, mixed> $a mai permisiv este respins cu varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). În versiunea 7.6, aceasta extinde și tipul fiecărui câmp la mixed, astfel încât fiecare apel esc_html() raportează argument.type. Mesajul varTag.nativeType afișează forma dedusă, fiind și cea mai rapidă metodă de a găsi adnotarea de copiat.

Versiunea Blockstudio 7.7 tratează $a ca definit în șabloanele blocurilor, astfel încât diagnosticele variable.undefined dispar, iar adnotarea devine opțională. În versiunea 7.7, șablonul defect de mai sus raportează patru erori în loc de șase, iar șablonul remediat trece fără linia @var.

Alegerea unei presetări

Instalarea pachetului activează doar extensia de bază. Comanda canonică rulează base dacă proiectul nu selectează altă presetare, așadar adăugarea dependenței nu activează de la sine straturile mai stricte.

Presetare Include
base Accesarea câmpurilor șablonului în PHP, Twig și Blade, verificări pentru etichetele blocurilor, validarea schemei pentru block.json, field.json, page.json, extensia JSON, căile db.php, rpc.php și cron.php, precum și numele hook-urilor Settings::get() și blockstudio/*.
theme Baza, plus rădăcinile temei și antetele style.css, resurse declarate în block.json în loc să fie adăugate manual în coadă, delimitarea %selector% în style.scss, valorile implicite ale câmpurilor și limitele repeaterelor.
extreme-theme Tema, plus opțiunile stricte PHPStan, apelurile shell și eval() respinse, scrierile $wpdb directe, escaparea ieșirii, verificările Tailwind, JavaScript și Interactivity API.
wordpress-render Tema extremă, plus o verificare de randare live pe care o furnizați sub forma unei comenzi.

Când configurația proiectului nu este inclusă, comanda canonică rulează și base, și theme la nivelul PHPStan max; extreme-theme setează singur max. Fiecare diagnostic de presetare are un identificator stabil blockstudio.*, listat în referința PHPStan.

Straturile pentru temă și extremă analizează și dincolo de fișierele PHP. Dacă unui câmp îi lipsește default, iar un script.js scrie în consolă, aceeași comandă raportează:

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

Aceste verificări sunt raportate prin memoria cache de rezultate a PHPStan. După editarea doar a unui block.json sau a unui script, memoria cache încălzită poate raporta [OK] No errors pentru starea veche. Folosiți --debug după --, care ocolește memoria cache, înainte de a avea încredere într-un rezultat fără erori pentru modificări care nu țin de PHP:

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

Opțiunile comenzii și codurile de ieșire

Valorile din linia de comandă înlocuiesc valorile blockstudio.json corespunzătoare pentru o singură execuție. Înlocuire înseamnă înlocuire: furnizarea oricărui --exclude elimină excludePaths configurat, așa că repetați vendor/** când adăugați unul:

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

Tot ce urmează după -- este transmis către PHPStan. Wrapperul mărește limita de memorie a PHPStan la 1G dacă nu furnizați propriul --memory-limit și își compune configurația în directorul temporar al sistemului, astfel încât niciun fișier generat nu ajunge în proiect. Comanda se încheie cu codul 0 dacă analiza trece, 1 dacă PHPStan raportează diagnostice și 2 pentru erori de utilizare, configurare sau execuție.

Rulați comanda canonică în loc să adăugați phpstan/extension-installer. Presetările includ deja extensia, iar când programul de instalare este prezent, același extension.neon este încărcat de două ori: PHPStan se oprește cu mesajul “This file is included multiple times” înainte de a analiza ceva.

Adoptarea într-un proiect existent

Un proiect analizat pentru prima dată va avea, de obicei, constatări. În loc să reduceți nivelul presetării, înregistrați-le într-o bază de referință, astfel încât codul nou să fie verificat conform tuturor regulilor:

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

Includeți baza de referință în configurația proiectului și indicați-i phpstan.configuration calea către aceasta:

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

Următoarea execuție raportează [OK] No errors cu constatările înregistrate, iar orice constatare nouă provoacă în continuare un eșec. Pentru presetarea base sau theme, setați și level: max sub parameters în phpstan.neon: comanda canonică setează singură acest nivel doar dacă nu este inclusă configurația proiectului.

Blocarea commit-urilor pe baza analizei

Cu "githooks": { "commit": true } în blockstudio.json, sincronizați o singură dată hook-ul gestionat după instalarea dependențelor:

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

Comanda scrie hook-ul în propriul director al Git, indică core.hooksPath către acesta și leagă în lanț orice hook pre-commit configurat anterior. Hook-ul rulează vendor/bin/blockstudio-phpstan -- --no-progress din rădăcina proiectului și nimic altceva: fără formatter și fără rescrieri. Commit-ul cu șablonul defect de mai devreme se oprește la analiză:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Setați commit la false și rulați din nou sync sau rulați vendor/bin/blockstudio-githooks remove pentru a restaura calea hook-ului anterioară. Sunt șterse doar fișierele scrise de Blockstudio.

Generarea contractului proiectului

Analiza îi spune unui agent ce a greșit după fapt. Un AGENTS.md îi spune dinainte: unde se află blocurile și paginile, cum ajung câmpurile la șabloane, ce funcționalități sunt activate și ce va respinge presetarea selectată. blockstudio-agents generează documentul din proiectul propriu-zis:

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

Pentru tema din acest ghid, fișierul generat începe astfel:

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.

Fiecare linie provine dintr-una dintre trei surse. Fișierele proiectului furnizează tipul proiectului, numărul de elemente, directoarele, spațiile de nume și limbajele șabloanelor. blockstudio.json furnizează funcționalitățile activate, astfel că hook-ul de commit apare la „Funcționalități activate”, iar vendor/bin/blockstudio-githooks sync la „Comenzi” doar pentru că este setat githooks.commit. Secțiunea despre corectitudine provine din presetarea selectată și este citită din fișierele presetării, strat cu strat:

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.

Menținerea la zi

Contractul devine învechit când se schimbă configurația. După activarea Tailwind în blockstudio.json, modul de verificare observă:

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

Se încheie cu codul 1, ceea ce permite folosirea sa ca pas CI alături de analiză. Regenerarea adaugă o intrare de funcționalitate „Tailwind CSS” și comanda wp bs tailwind compile.

Note păstrate la regenerare

Fișierul se încheie cu o secțiune pentru note. Orice text dintre marcajele ei este păstrat identic la fiecare regenerare, octet cu octet, așa că aici trebuie trecute informațiile despre proiect care nu pot fi deduse din fișiere:

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

Generatorul nu înlocuiește niciodată un fișier pe care nu l-a scris. Dacă îl rulați pentru un fișier AGENTS.md scris manual, refuză și se încheie cu codul 2:

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

Pentru a păstra textul scris manual, copiați-l temporar, rulați cu --force și inserați-l în secțiunea pentru note. Celelalte opțiuni sunt --root, --config, --output și --stdout, care afișează contractul în loc să îl scrie.

Ce se schimbă în Blockstudio 7.7

Pachetul 7.7 păstrează comenzile, presetările și codurile de ieșire descrise aici. Pe parcursul redactării ghidului cu această versiune s-au observat două diferențe: $a nu mai are nevoie de o adnotare, după cum se explică în secțiunea de remediere, iar contractul generat descrie mai amplu validarea etichetelor blocurilor, acoperind elementele HTML mapate la blocuri în sursele paginilor și atributele globale pe care o etichetă le poate transmite mai departe.

Pașii următori

  • PHPStan referință: fiecare regulă, parametru presetat, structură de tip pentru câmpuri, probă de randare în timp real și identificator de diagnostic.
  • Integrare AI: indexul documentației pentru agenți de programare, care completează contractul proiectului.
  • Programare cu Blockstudio: colaborarea cu agenți de programare la un proiect Blockstudio.
  • Carte de rețete pentru tipare de câmpuri: structuri de câmpuri ale căror chei de șablon sunt înțelese de analiză, inclusiv grupuri și repetoare.