Pereiti prie turinio

Patikrinti šablonai su PHPStan ir sugeneruotu AGENTS.md

Blockstudio bloką sudaro du failai, kurių turinys turi sutapti. block.json aprašo laukus, o šablonas nuskaito juos kaip $a['id']. Vykdymo metu niekas netrukdo šablonui nuskaityti rakto, kuris buvo pervadintas, niekada nebuvo deklaruotas arba parašytas su klaida. Jis tiesiog atvaizduoja tuščią eilutę, o klaida išaiškėja tik kam nors pastebėjus tuščią antraštę veikiančiame puslapyje. Tas pats pasakytina apie išvesties kodavimą: neekranuotas echo veikia puikiai, kol lauko reikšmėje neatsiranda žymėjimo kalbos.

Paketas blockstudio/phpstan abi problemas perkelia į analizės etapą. Jis nuskaito jūsų block.json failus, pagal juos nustato $a tipus ir praneša apie neatitinkančius šablonų nuskaitymus. Pasirenkami išankstiniai nustatymai papildo patikras temos struktūros taisyklėmis, kodavimu, taip pat JavaScript ir Tailwind patikromis. Kartu su paketu pateikiamos dvi papildomos priemonės: valdoma priešįrašymo užkarda, vykdanti analizę, ir generatorius, sukuriantis AGENTS.md su jūsų projekto aprašu kodą rašantiems agentams.

Šiame vadove sukursime nedidelę temą, tyčia sugadinsime vieną jos šabloną, peržiūrėsime analizės išvestį, pataisysime šabloną ir nustatysime pakeitimų užkardą bei agento sutartį.

Temos sąranka

Pradėkite nuo temos katalogo, kuriame yra style.css antraštė, composer.json ir vienas blokas:

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

Įdiekite paketą kaip kūrimo priklausomybę:

Shell
composer require --dev blockstudio/phpstan

Įdiegiamos PHPStan ir szepeviktor/phpstan-wordpress esančios WordPress deklaracijos, o vendor/bin įdiegiami trys vykdomieji failai: blockstudio-phpstan, blockstudio-githooks ir blockstudio-agents.

Tada nurodykite analizei, ką vykdyti. Viso projekto numatytosios nuostatos saugomos blockstudio.json objekto phpstan lauke, todėl interaktyvi analizė, CI ir pakeitimų užkarda naudoja tuos pačius nustatymus:

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

extreme-theme yra griežčiausias iš trijų statinių išankstinių nustatymų. Toliau esančioje lentelėje paaiškinta, ką prideda kiekvienas iš jų. excludePaths neįtraukia Composer failų į Blockstudio nuskaitymą ir PHP analizę.

Sąmoningai sugadinkite šabloną

Herojaus bloke deklaruotas vienas laukas:

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

Šablonas teisingai nuskaito šį lauką, o tada nuskaito subtitle, kurio blokas nedeklaravo, ir išveda jį be kodavimo:

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

Redaktoriuje ir svetainės priekinėje dalyje atvaizduojama tuščia pastraipa, bet klaida nepateikiama. Vietoj to paleiskite analizę:

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

Komanda baigiama kodu 1. Diagnostikos pranešimai, išdėstyti nuo konkrečiausio iki bendriausio:

  • blockstudio.field yra šablono taisyklė. Ji rado šalia šablono esantį block.json, nustatė jo laukus, o subtitle nėra vienas iš jų.
  • offsetAccess.notFound taip pat daro tokią išvadą apie patį PHPStan, nes plėtinys suteikia $a konkrečią formą array{heading: string}, išvestą iš block.json. Kiekvienas lauko tipas atitinka PHP tipą: text yra string, toggle yra bool, kartotinis yra eilučių formų masyvas.
  • blockstudio.output.unescaped kyla iš extreme-theme sluoksnio. Išvesti atributų reikšmes galima tik jas perdavus kodavimo funkcijai, pavyzdžiui, esc_html(), esc_attr(), esc_url() arba wp_kses_post().
  • echo.nonString kyla iš nežinomo rakto: neegzistuojančiam poslinkiui nepriskirtas eilutės tipas, todėl jo negalima išvesti.
  • variable.undefined atsiranda todėl, kad PHPStan mato šablono failą, o ne atvaizdavimo funkciją, kuri prieš įtraukdama šabloną apibrėžia $a. Apie tai rašoma pataisymo skyriuje.

Pataisymas

Nuspręskite, ar subtitle yra tikras laukas. Šiuo atveju taip, todėl jį deklaruokite ir nurodykite default, nes temos sluoksnyje jis privalomas kiekvienam laukui:

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

Užkoduokite išvestį ir deklaruokite $a su plėtinio nustatyta forma:

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

Įrašykite tiksliai atitinkančią formą. Kanoninė komanda vykdo PHPStan lygiu max, o laisvesnis @var array<string, mixed> $a atmetamas su varTag.nativeType (“PHPDoc žyma @var su tipu array<string, mixed> nėra vietinio array{heading: string, subtitle: string} tipo potipis). 7.6 versijoje visi laukai taip pat praplečiami iki mixed, todėl kiekvienas esc_html() iškvietimas pateikia argument.type. Pranešime varTag.nativeType rodoma nustatyta forma, todėl taip greičiausia rasti, kokią anotaciją nukopijuoti.

Blockstudio 7.7 versijoje $a laikomas apibrėžtu blokų šablonuose, todėl variable.undefined diagnostikos pranešimai išnyksta, o anotacija tampa neprivaloma. Tikrinant su 7.7 versija, aukščiau pateiktas sugadintas šablonas pateikia keturias, o ne šešias klaidas, o pataisytas šablonas praeina ir be eilutės @var.

Pasirinkite išankstinį nustatymą

Įdiegus paketą įjungiamas tik bazinis plėtinys. Kanoninė komanda vykdo base, nebent projektui parenkamas kitas išankstinis nustatymas, todėl vien priklausomybės pridėjimas griežtesnių sluoksnių neįjungia.

Išankstinis nustatymas Pridedamos patikros
base Šablono laukų prieigos PHP, Twig ir Blade, blokų žymų patikros, block.json, field.json, page.json schemų tikrinimas, plėtinio JSON, db.php, rpc.php ir cron.php keliai bei Settings::get() blockstudio/* veiksmo pavadinimai.
theme Bazinis nustatymas ir temų šakniniai katalogai bei style.css antraštės, block.json deklaruoti ištekliai, o ne rankiniu būdu įtraukti, %selector% aprėptis style.scss, numatytosios laukų reikšmės ir kartotinių ribos.
extreme-theme Temos nustatymas ir griežtos PHPStan vėliavėlės, atmesti apvalkalo ir eval() iškvietimai, tiesioginiai $wpdb įrašai, išvesties kodavimas, Tailwind, JavaScript ir Interactivity API patikros.
wordpress-render Griežčiausias temos nustatymas ir jūsų pateikiamas tiesioginio atvaizdavimo bandymas, vykdomas kaip komanda.

Jei projekto konfigūracija nepateikta, kanoninė komanda taip pat vykdo base ir theme su PHPStan lygio reikšme max; pats extreme-theme nustato max. Kiekviena išankstinio nustatymo diagnostika turi stabilų blockstudio.* identifikatorių, pateiktą PHPStan žinyne.

Temos ir griežčiausias sluoksniai tikrina ir PHP failus. Jei lauke trūksta default, o script.js įrašo duomenis į konsolę, ta pati komanda pateikia:

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

Šios patikros pateikiamos per PHPStan rezultatų talpyklą. Pakeitus tik block.json arba scenarijų, šilta talpykla gali pateikti senos būsenos [OK] No errors. Po -- perduokite --debug, kad talpykla būtų apeita, ir prieš pasitikėdami sėkmingu rezultatu, jei pakeitimai nėra PHP, išvalykite talpyklą:

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

Komandos parinktys ir išėjimo kodai

Komandinės eilutės reikšmės vienam paleidimui pakeičia atitinkamas blockstudio.json reikšmes. Pakeičia reiškia pakeičia: perdavus bent vieną --exclude, konfigūruotas excludePaths nebeperduodamas, todėl pridėdami parinktį pakartokite 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":[]}

Viskas po -- perduodama PHPStan. Apvalkalas padidina PHPStan atminties limitą iki 1G, nebent nurodote savo --memory-limit, o konfigūracija sudaroma sistemos laikinojoje direktorijoje, todėl projekte nesukuriamas joks sugeneruotas failas. Jei analizė sėkminga, išeinama su kodu 0; jei PHPStan pateikia diagnostikos pranešimų, išeinama su kodu 1; naudojimo, konfigūracijos ar vykdymo klaidų atveju – su kodu 2.

Vykdykite ją kanonine komanda, o ne pridėkite phpstan/extension-installer. Išankstiniai nustatymai plėtinį jau įtraukia, todėl, esant įdiegimo programai, tas pats extension.neon įkeliamas dukart: PHPStan sustoja su pranešimu “This file is included multiple times” dar neprasidėjus analizei.

Pritaikykite esamam projektui

Pirmą kartą analizuojant projektą paprastai randama pažeidimų. Užuot sušvelninę išankstinį nustatymą, įrašykite juos į pradinę atskaitą, kad naujam kodui būtų taikomos visos taisyklės:

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

Įtraukite pradinę atskaitą į projekto konfigūraciją ir nurodykite phpstan.configuration jos vietą:

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

Kito vykdymo metu pateikiami [OK] No errors pranešimai, atsižvelgiant į užfiksuotus pažeidimus; nauji pažeidimai vis tiek sukelia klaidą. Jei naudojate base arba theme išankstinį nustatymą, taip pat nustatykite level: max skiltyje parameters faile phpstan.neon: kanoninė komanda šį lygį nustato pati tik tada, kai projekto konfigūracija nepateikta.

Užkirskite kelią pažeidimų įrašymui

Jei "githooks": { "commit": true } įrašytas faile blockstudio.json, įdiegę priklausomybes vieną kartą sinchronizuokite valdomą užkardą:

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

Komanda įrašo užkardą į paties Git katalogą, nurodo core.hooksPath naudoti ją ir paleidžia anksčiau sukonfigūruotą priešįrašymo užkardą. Užkarda iš projekto šakninio katalogo vykdo tik vendor/bin/blockstudio-phpstan -- --no-progress: jokio formatavimo ar perrašymo. Anksčiau pateikto sugadinto šablono įrašymas sustoja analizės etape:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Nustatykite commit reikšmę false ir vėl paleiskite sync arba vykdykite vendor/bin/blockstudio-githooks remove, kad atkurtumėte ankstesnį užkardos kelią. Ištrinami tik failai, kuriuos sukūrė Blockstudio.

Sugeneruokite projekto sutartį

Analizė po fakto parodo agentui, ką jis padarė ne taip. AGENTS.md iš anksto nurodo, kur saugomi blokai ir puslapiai, kaip laukai pasiekia šablonus, kurios funkcijos įjungtos ir ką parinktas išankstinis nustatymas atmes. blockstudio-agents sugeneruoja šį dokumentą iš paties projekto:

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

Šiame vadove aprašytai temai sugeneruotas failas prasideda taip:

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.

Kiekviena eilutė gaunama iš vieno iš trijų šaltinių. Projekto failai nurodo projekto tipą, objektų skaičius, katalogus, vardų sritis ir šablonų kalbas. blockstudio.json pateikia įjungtas funkcijas, todėl pakeitimų užkarda rodoma skiltyje “Įjungtos funkcijos”, o vendor/bin/blockstudio-githooks sync skiltyje “Komandos” atsiranda tik todėl, kad nustatyta githooks.commit. Pasirinktas išankstinis nustatymas pateikia teisingumo patikrų skyrių, perskaitomą iš išankstinio nustatymo failų sluoksnis po sluoksnio:

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.

Atnaujinkite pagal pakeitimus

Pasikeitus konfigūracijai sutartis pasensta. Įjungus Tailwind faile blockstudio.json, tikrinimo režimas tai aptinka:

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

Komanda baigiama kodu 1, todėl ją galima naudoti kaip CI žingsnį greta analizės. Sugeneravus iš naujo pridedamas funkcijos “Tailwind CSS” įrašas ir komanda wp bs tailwind compile.

Pastabos išsaugomos generuojant iš naujo

Failo pabaigoje yra pastabų sritis. Viskas tarp jos žymeklių išsaugoma baitas į baitą kiekvieną kartą generuojant iš naujo, todėl ten įrašykite projekto žinias, kurių negalima nustatyti iš failų:

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

Generatorius niekada nepakeičia failo, kurio pats nesukūrė. Jei nurodysite ranka parašytą AGENTS.md, jis atsisakys veikti ir baigs darbą kodu 2:

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

Jei norite išsaugoti ranka parašytą tekstą, nukopijuokite jį kitur, paleiskite su --force ir įklijuokite į pastabų sritį. Kitos parinktys: --root, --config, --output ir --stdout; ši parinktis atspausdina sutartį, o ne įrašo ją į failą.

Kas keičiasi Blockstudio 7.7 versijoje

7.7 versijos pakete paliekamos čia aprašytos komandos, išankstiniai nustatymai ir išėjimo kodai. Rengiant šį vadovą pagal šią versiją paaiškėjo du skirtumai: $a nebereikia anotacijos, kaip aprašyta pataisymo skyriuje, o sugeneruotoje sutartyje blokų žymų tikrinimas aprašomas plačiau – įtraukiami puslapių šaltinių HTML elementai, susieti su blokais, ir visuotiniai atributai, kuriuos žyma gali perduoti toliau.

Tolesni veiksmai

  • PHPStan nuoroda: kiekviena taisyklė, išankstinis nustatymas, lauko tipo struktūra, tiesioginio atvaizdavimo patikra ir diagnostinis identifikatorius.
  • Integracija su DI: dokumentacijos rodyklė programavimo agentams, papildanti jūsų projekto sutartį.
  • Vibekodavimas su Blockstudio: darbas su kodavimo agentais Blockstudio projekte.
  • Laukų šablonų receptų knyga: laukų struktūros, kurių šablonų raktus supranta analizė, įskaitant grupes ir kartotuvus.