Liigu sisu juurde

Kontrollitud mallid PHPStan abil ja loodud AGENTS.md

Blockstudio plokk koosneb kahest failist, mis peavad omavahel sobima. block.json määratleb väljad ja mall loeb neid kui $a['id']. Käitamise ajal ei takista miski mallil lugemast võtit, mis on ümber nimetatud, määratlemata või valesti kirjutatud. Tulemuseks on lihtsalt tühi string ning viga tuleb ilmsiks alles siis, kui keegi märkab avalikul lehel tühja pealkirja. Sama kehtib väljundi paokaitse kohta: paokaitseta echo töötab laitmatult seni, kuni välja väärtus sisaldab märgendust.

Pakett blockstudio/phpstan nihutab mõlemad probleemid analüüsiaega. See loeb teie block.json faile, tuletab nende põhjal väljade tüübid $a ja annab teada mallis leiduvatest lugemistoimingutest, mis nendega ei sobi. Valikulised eelseadistused lisavad teema struktuurireeglid, paokaitse ning kontrollid JavaScript ja Tailwind jaoks. Sama pakett sisaldab kaht lisatööriista: hallatud pre-commit-hook’i, mis käivitab analüüsi, ning generaatorit, mis kirjutab koodiagentidele teie projekti kirjeldava AGENTS.md.

Selles juhendis loote väikese teema, lõhute tahtlikult ühe selle malli, uurite analüüsi väljundit, parandate vea ning seadistate seejärel sissekannete värava ja agendilepingu.

Teema seadistamine

Alustage teemakaustast, milles on päis style.css, fail composer.json ja üks plokk:

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

Paigaldage pakett arendussõltuvusena:

Shell
composer require --dev blockstudio/phpstan

See lisab sõltuvustena PHPStan ja szepeviktor/phpstan-wordpress paketist pärit WordPress tüübimääratlused ning paigaldab kataloogi vendor/bin kolm käivitatavat faili: blockstudio-phpstan, blockstudio-githooks ja blockstudio-agents.

Seejärel määrake, mida analüüs käivitab. Projektiülesed vaikesätted asuvad objektis phpstan failis blockstudio.json, nii et interaktiivsed käivitused, CI ja sissekannete hook loevad kõiki samu seadeid:

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

extreme-theme on kolmest staatilisest eelseadistusest rangeim. Allpool olev tabel selgitab, mida igaüks lisab. excludePaths jätab Composer enda failid skannimisest Blockstudio ja analüüsist PHP välja.

Malli tahtlik rikkumine

Hero-plokk määratleb ühe välja:

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

Mall loeb välja õigesti, kuid loeb seejärel subtitle, mida plokis pole kunagi määratletud, ja väljastab selle paokaitseta:

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

Redaktoris ja esiosas renderdatakse tühi lõik ning viga ei kuvata. Käivitage selle asemel analüüs:

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

Käsk väljub koodiga 1. Vaatame diagnostikateateid kõige täpsemast üldisemani:

  • blockstudio.field on mallireegel. See leidis malli kõrval block.json, tuvastas selle väljad ja leidis, et subtitle nende hulka ei kuulu.
  • offsetAccess.notFound jõuab sama järelduseni ka PHPStan enda kaudu, sest laiendus annab $a konkreetse kuju array{heading: string}, mis tuletatakse väärtusest block.json. Iga välja tüüp vastab PHP tüübile: text on string, toggle on bool ning kordusväli on reastruktuuride massiiv.
  • blockstudio.output.unescaped pärineb kihi extreme-theme. Väljastatud atribuudi väärtused tuleb paokaitsta sellise funktsiooniga nagu esc_html(), esc_attr(), esc_url() või wp_kses_post().
  • echo.nonString tuleneb tundmatust võtmest: olematul nihkel pole väljastamiseks stringitüüpi.
  • variable.undefined ilmub, sest PHPStan näeb mallifaili, mitte renderdusfunktsiooni, mis määratleb enne faili kaasamist $a. Parandusjaotis käsitleb seda.

Parandamine

Otsustage, kas subtitle on päriselt olemasolev väli. Siin on see olemas, seega määratlege see ning lisage default, sest teemakiht nõuab seda igalt väljalt:

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

Paokaitske väljund ning määratlege $a laienduse tuletatud kujuga:

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

Kirjutage annotatsioon täpse kujuna. Kanooniline käsk käivitab taseme max juures käsu PHPStan, kus lõdvem @var array<string, mixed> $a lükatakse tagasi veaga varTag.nativeType (“PHPDoc-märgend @var tüübiga array<string, mixed> ei ole alamtüüp natiivsest tüübist array{heading: string, subtitle: string}”). Versioonis 7.6 laiendab see ka kõik väljad tüübiks mixed, mistõttu iga esc_html() väljakutse annab vea argument.type. Sõnum varTag.nativeType kuvab tuletatud kuju, nii et selle abil leiate kopeeritava annotatsiooni kõige kiiremini.

Blockstudio 7.7 käsitleb plokimalle nii, nagu $a oleks neis määratletud, seega kaovad diagnostikateated variable.undefined ja annotatsioon muutub valikuliseks. Versioonis 7.7 annab ülal toodud vigane mall kuue vea asemel neli ning parandatud mall läbib kontrolli ilma reata @var.

Eelseadistuse valimine

Paketi paigaldamisel lubatakse ainult baaslaiendus. Kui projekt ei vali muud eelseadistust, käivitab kanooniline käsk base, seega sõltuvuse lisamine üksi rangemaid kihte ei aktiveeri.

Eelseadistus Lisab
base Mallide väljapääsud failides PHP, Twig ja Blade, plokimärgendite kontrollid, skeemivalideerimine block.json, field.json, page.json, laienduse JSON, db.php, rpc.php ja teede cron.php, Settings::get() ning hook’i nimed blockstudio/* jaoks.
theme Baas ning teema juurkataloogid ja style.css päised, failis block.json deklareeritud varad käsitsi järjekorda lisatavate asemel, style.scss ulatuse määramine %selector%-is, välja vaikeväärtused ja kordusvälja piirangud.
extreme-theme Teema koos rangete PHPStan lippudega, keelatud shell’i- ja eval()-kutsetega, toorete $wpdb kirjutamistega, väljundi paokaitsega ning Tailwind, JavaScript ja interaktiivsuskihi API kontrollidega.
wordpress-render Äärmuslik teema koos käsuna ette antava reaalajas renderduse kontrolliga.

Kui projekti konfiguratsioon puudub, käivitab kanooniline käsk ka base ja theme tasemel PHPStan max; extreme-theme määrab ise väärtuse max. Igal eelseadistuse diagnostikateatel on püsiv blockstudio.* identifikaator, mis on loetletud viites PHPStan.

Teema- ja äärmuslik kiht kontrollivad ka faile PHP. Kui väljal puudub default ja script.js logib konsooli, teatab sama käsk järgmist:

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

Neid kontrolle hallatakse PHPStan tulemuste vahemälu kaudu. Kui muudate ainult faili block.json või skripti, võib soojendatud vahemälu näidata vana oleku kohta väärtust [OK] No errors. Enne -- läbimist lisage lipp --debug, mis jätab vahemälu vahele, enne kui usaldate muudatuste puhul, mis pole PHP-ga seotud, edukat tulemust:

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

Käsurea valikud ja väljumiskoodid

Käsurea väärtused asendavad ühe käivituse ajaks vastavad blockstudio.json väärtused. Asendamine tähendab täielikku asendamist: mis tahes --exclude edastamisel jäetakse seadistatud excludePaths välja, seega lisage uue lisamisel uuesti 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":[]}

Kõik pärast -- edastatakse käsule PHPStan. Ümbris suurendab PHPStan mälulimiidi väärtuseni 1G, kui te ei anna enda --memory-limit väärtust, ning koostab konfiguratsiooni süsteemi ajutises kataloogis, nii et projektikataloogi ei teki genereeritud faile. Eduka analüüsi korral väljub see koodiga 0, diagnostikateadete puhul koodiga 1 ja kasutus-, konfiguratsiooni- või käivitusvigade puhul koodiga 2 PHPStan.

Käivitage see kanoonilise käsu kaudu, mitte lisades phpstan/extension-installer. Eelseadistused sisaldavad laiendust juba ise ning kui paigaldaja on olemas, laaditakse sama extension.neon kaks korda: PHPStan peatub teatega “This file is included multiple times” enne analüüsi alustamist.

Olemasoleva projektiga alustamine

Esimesel analüüsil leitakse projektist tavaliselt vigu. Eelseadistuse nõuete leevendamise asemel salvestage need lähteandmestikku, et uuele koodile kehtiksid kõik reeglid:

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

Lisage lähteandmestik projekti konfiguratsiooni ja määrake selle asukoht väärtusega phpstan.configuration:

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

Järgmisel käivitamisel teatatakse [OK] No errors, samal ajal kui salvestatud leiud on arvesse võetud; kõik uued leiud põhjustavad endiselt vea. Eelseadistuse base või theme kasutamisel määrake level: max jaotises parameters failis phpstan.neon: kanooniline käsk määrab selle taseme ise ainult siis, kui projekti konfiguratsiooni pole kaasatud.

Sissekannete piiramine analüüsi tulemusega

Kui "githooks": { "commit": true } on failis blockstudio.json, sünkroonige hallatud hook pärast sõltuvuste paigaldamist ühe korra:

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

Käsk kirjutab hook’i kausta Git, suunab core.hooksPath selle juurde ja ühendab selle varem seadistatud pre-commit hook’iga. Hook käivitab projekti juurkataloogist ainult käsu vendor/bin/blockstudio-phpstan -- --no-progress: ei vorminda ega kirjuta faile ümber. Varem toodud vigase malli sissekandmine peatub analüüsi juures:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Eelmise hook’i asukoha taastamiseks määrake commit väärtuseks false ja käivitage uuesti sync või käivitage vendor/bin/blockstudio-githooks remove. Kustutatakse ainult failid, mille kirjutas Blockstudio.

Projekti lepingu loomine

Analüüs annab agendile tagantjärele teada, mida ta valesti tegi. AGENTS.md annab sellest teada ette: kus plokid ja lehed asuvad, kuidas väljad mallidesse jõuavad, millised funktsioonid on lubatud ja mida valitud eelseadistus tagasi lükkab. blockstudio-agents loob selle dokumendi otse projektist:

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

Selle juhendi teema puhul algab loodud fail nii:

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.

Iga rida pärineb ühest kolmest allikast. Projekti failidest saadakse projekti tüüp, arvud, kataloogid, nimeruumid ja mallikeeled. Lubatud funktsioonid annab blockstudio.json, seega kuvatakse sissekannete hook jaotises „Lubatud funktsioonid” ning vendor/bin/blockstudio-githooks sync jaotises „Käsud” ainult seetõttu, et määratud on githooks.commit. Valitud eelseadistus määrab õigsuse jaotise, mis koostatakse eelseadistuse failidest kiht kihi haaval:

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.

Hoidke see ajakohasena

Konfiguratsiooni muutudes muutub leping aegunuks. Pärast Tailwind lubamist failis blockstudio.json tuvastab kontrollrežiim selle:

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

See väljub koodiga 1, nii et seda saab kasutada CI-s analüüsi kõrval. Uuesti genereerimisel lisandub funktsioonikirje „Tailwind CSS” ja käsk wp bs tailwind compile.

Märkused, mis säilivad uuesti genereerimisel

Faili lõpus on märkuste ala. Kõik selle märgendite vahele jääv säilitatakse iga uuesti genereerimise korral baithaaval, seega paigutage sinna projektiteave, mida ei saa failidest tuletada:

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

Generaator ei asenda kunagi faili, mida ta ise pole kirjutanud. Käsitsi kirjutatud faili AGENTS.md puhul keeldub see töötamast ja väljub koodiga 2:

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

Käsitsi kirjutatud teksti säilitamiseks kopeerige see kõrvale, käivitage käsuga --force ja kleepige tekst märkuste alasse. Muud valikud on --root, --config, --output ja --stdout; viimane prindib lepingu selle kirjutamise asemel.

Mis muutub versioonis Blockstudio 7.7

Versiooni 7.7 pakett säilitab siin kirjeldatud käsud, eelseadistused ja väljumiskoodid. Selle juhendi koostamisel selgus kaks erinevust: $a ei vaja enam parandamise jaotises kirjeldatud annotatsiooni ning loodud leping kirjeldab plokimärgendite valideerimist laiemalt, hõlmates lehe allikates plokkidega seostatud HTML elemente ja globaalseid atribuute, mida märgend võib edasi anda.

Järgmised sammud

  • PHPStan viide: kõik reeglid, eelseadistatud parameetrid, väljade tüübid ja struktuurid, reaalajas renderduse kontroll ning diagnostilised identifikaatorid.
  • AI Integration: kodeerimisagentidele mõeldud dokumentatsiooni register, mis täiendab teie projekti lepingut.
  • Vibecoding koos Blockstudio: koostöö kodeerimisagentidega Blockstudio projektis.
  • Field Patterns Cookbook: väljade struktuurid, mille mallivõtmeid analüüs tunneb, sealhulgas rühmad ja kordajad.