Tarkistetut mallipohjat: PHPStan ja luotu AGENTS.md
Blockstudio-lohko koostuu kahdesta tiedostosta, joiden on vastattava toisiaan. block.json määrittelee kentät, ja mallipohja lukee niiden arvot muodossa $a['id']. Ajonaikainen ympäristö ei estä mallipohjaa lukemasta avainta, joka on nimetty uudelleen, jätetty määrittelemättä tai kirjoitettu väärin. Se vain tuottaa tyhjän merkkijonon, ja virhe huomataan vasta, kun joku näkee tyhjän otsikon julkaistulla sivulla. Sama koskee tulosteen suojausta: suojaamaton echo toimii moitteettomasti, kunnes kentän arvo sisältää merkintäkieltä.
blockstudio/phpstan-paketti siirtää molempien ongelmien havaitsemisen analyysivaiheeseen. Se lukee block.json-tiedostosi, määrittää niistä $a-tyypit ja ilmoittaa mallipohjien luvuista, jotka eivät vastaa kenttiä. Valinnaiset esiasetukset lisäävät teeman rakennesääntöjä, tulosteen suojauksen sekä JavaScript- ja Tailwind-tarkistukset. Sama paketti sisältää kaksi apuohjelmaa: hallitun esicommit-koukun, joka suorittaa analyysin, sekä generaattorin, joka luo projektiasi kuvaavan AGENTS.md-tiedoston koodausagenteille.
Tässä oppaassa rakennetaan pieni teema, rikotaan yksi sen mallipohjista tarkoituksella, tarkastellaan analyysin tuloksia, korjataan virhe ja otetaan sitten käyttöön commit-esto sekä agenttisopimus.
Teeman määrittäminen
Aloita teemakansiosta, jossa on style.css-otsake, composer.json ja yksi lohko:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Asenna paketti kehitysriippuvuutena:
composer require --dev blockstudio/phpstan
Se asentaa PHPStan-paketin ja szepeviktor/phpstan-wordpress-palvelun WordPress-tyngät sekä kolme suoritettavaa tiedostoa kansioon vendor/bin: blockstudio-phpstan, blockstudio-githooks ja blockstudio-agents.
Määritä seuraavaksi, mitä analyysissä suoritetaan. Projektin yleiset oletukset ovat tiedoston blockstudio.json phpstan-objektissa, joten vuorovaikutteiset suoritukset, CI ja commit-koukku käyttävät samoja asetuksia:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
extreme-theme on kolmesta staattisesta esiasetuksesta tiukin. Alempana oleva taulukko kertoo, mitä kukin niistä lisää. excludePaths pitää Composer-järjestelmän omat tiedostot poissa Blockstudio-tarkistuksesta ja PHP-analyysistä.
Riko mallipohja tarkoituksella
Hero-lohko määrittelee yhden kentän:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Mallipohja lukee kentän oikein ja yrittää sen jälkeen lukea subtitle, jota lohko ei ole määritellyt, sekä tulostaa sen ilman suojausta:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
Editorissa ja käyttöliittymässä tämä tuottaa tyhjän kappaleen ilman virheilmoitusta. Suorita sen sijaan analyysi:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
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
Komento päättyy koodiin 1. Tarkastellaan diagnostiikkaa tarkimmasta alkaen:
blockstudio.fieldon mallipohjasääntö. Se löysi mallipohjan vierestäblock.json-tiedoston, selvitti sen kentät ja totesi, etteisubtitlekuulu niihin.offsetAccess.notFoundon PHPStan itse, joka päätyy samaan tulokseen, koska laajennus antaa koodille$akonkreettisen muodonarray{heading: string}, joka on johdettu lähteestäblock.json. Jokainen kenttätyyppi vastaa PHP-tyyppiä:textonstring,toggleonboolja toistokenttä rivimuotojen taulukko.blockstudio.output.unescapedtuleeextreme-theme-kerroksesta. Tulostettavat attribuuttiarvot on suojattava käsittelemällä ne suojausfunktiolla, kutenesc_html(),esc_attr(),esc_url()taiwp_kses_post().echo.nonStringjohtuu tuntemattomasta avaimesta: olemattomalle offsetille ei ole määritetty merkkijonotyyppiä, joka voitaisiin tulostaa.variable.undefinedtulee siitä, että PHPStan näkee mallipohjatiedoston eikä renderöintifunktiota, joka määrittää$a-arvon ennen tiedoston sisällyttämistä. Korjaus käsitellään myöhemmin.
Korjaa virhe
Päätä, onko subtitle oikea kenttä. Tässä se on, joten määritä se. Teemakerros edellyttää, että jokaisella kentällä on default:
{
"$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": "" }
]
}
}
Suojaa tuloste ja määritä $a laajennuksen päättelemässä muodossa:
<?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>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Kirjoita annotaatio täsmälleen päättelemäsi muotoiseksi. Kanonisessa komennossa PHPStan suoritetaan tasolla max, jolla väljempi @var array<string, mixed> $a hylätään varTag.nativeType-virheellä (“PHPDoc-tunniste @var, jonka tyyppi on array<string, mixed>, ei ole natiivin tyypin array{heading: string, subtitle: string} alatyyppi). Versiossa 7.6 jokainen kenttä laajenee lisäksi tyyppiin mixed, joten jokainen esc_html()-kutsu ilmoittaa virheestä argument.type. varTag.nativeType-viesti tulostaa päätellyn muodon, joten sen avulla löydät nopeimmin kopioitavan annotaation.
Blockstudio 7.7 käsittelee lohkon mallipohjissa $a-arvon määriteltynä, joten variable.undefined-diagnostiikka katoaa ja annotaatio muuttuu valinnaiseksi. Versiota 7.7 vasten rikkinäinen mallipohja ilmoittaa neljä virhettä kuuden sijaan, ja korjattu mallipohja läpäisee tarkistuksen ilman @var-riviä.
Valitse esiasetus
Paketin asentaminen ottaa käyttöön vain peruslaajennuksen. Kanoninen komento suorittaa base-esiasetuksen, ellei projekti valitse toista, joten riippuvuuden lisääminen ei itsessään ota tiukempia kerroksia käyttöön.
| Esiasetus | Lisää |
|---|---|
base |
Mallipohjien kenttien käyttö kohteissa PHP, Twig ja Blade, lohkotunnisteiden tarkistukset, block.json-mallien, field.json-, page.json– ja JSON-laajennusten sekä db.php-, rpc.php– ja cron.php-rakenteiden skeeman validointi, Settings::get()-polut ja blockstudio/*-koukkujen nimet. |
theme |
Perusasetusten lisäksi teemojen juurihakemistot ja style.css-otsakkeet, kohteessa block.json määritetyt resurssit manuaalisen jonoon lisäämisen sijaan, style.scss-rajaus kohteessa %selector%, kenttien oletusarvot ja toistokenttien rajat. |
extreme-theme |
Teema-asetusten lisäksi tiukat PHPStan-liput, hylätyt komentotulkin ja eval()-kutsut, suorat $wpdb-kirjoitukset, tulosteen suojaus, Tailwind-, JavaScript- ja Interactivity API -tarkistukset. |
wordpress-render |
Äärimmäinen teema sekä tarjoamasi komentona suoritettava reaaliaikainen renderöintitesti. |
Kun projektimääritystä ei ole mukana, kanoninen komento suorittaa myös base– ja theme-esiasetukset tasolla PHPStan max; extreme-theme asettaa itse arvon max. Jokaisella esiasetuksen diagnostiikalla on pysyvä blockstudio.*-tunniste, joka on lueteltu PHPStan-viitteessä.
Teema- ja ääritasot tarkistavat myös PHP-tiedostojen sisällön. Kun kentältä puuttuu default ja script.js kirjaa tietoja konsoliin, sama komento ilmoittaa seuraavaa:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Nämä tarkistukset ilmoitetaan PHPStan-järjestelmän tulosvälimuistin kautta. Jos muokkaat vain block.json-tiedostoa tai skriptiä, lämmin välimuisti voi ilmoittaa vanhan tilan [OK] No errors. Käytä komentoa --debug ---komennon jälkeen, jolloin välimuisti ohitetaan, ennen kuin luotat onnistuneeseen tulokseen muissa kuin PHP-muutoksissa:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Komennon valinnat ja poistumiskoodit
Komentorivin arvot korvaavat niitä vastaavat blockstudio.json-arvot yhden suorituksen ajaksi. Korvaaminen tarkoittaa korvaamista: minkä tahansa --exclude-arvon välittäminen poistaa määritetyn excludePaths-arvon, joten lisää vendor/** uudelleen, kun lisäät arvon:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Kaikki ---merkkijonon jälkeinen välitetään ohjelmalle PHPStan. Kääre nostaa ohjelman PHPStan muistirajan arvoon 1G, ellet anna omaa --memory-limit-arvoa. Se muodostaa määrityksen järjestelmän väliaikaishakemistossa, joten projektiin ei luoda tiedostoja. Komento päättyy koodiin 0, kun analyysi onnistuu, koodiin 1, kun PHPStan ilmoittaa virheitä, ja koodiin 2 käyttöä, määritystä tai suoritusta koskevissa virheissä.
Suorita komento kanonisen komennon kautta sen sijaan, että lisäisit phpstan/extension-installer-määrityksen. Esiasetukset sisältävät jo laajennuksen, ja jos asennusohjelma on käytössä, sama extension.neon ladataan kahdesti: PHPStan pysähtyy ilmoitukseen “This file is included multiple times” ennen analyysin aloittamista.
Ota käyttöön olemassa olevassa projektissa
Ensimmäisellä analyysikerralla projektista löytyy yleensä huomautettavaa. Sen sijaan, että lievennät esiasetusta, kirjaa nykyiset löydökset lähtötilanteeseen, niin uutta koodia koskevat täydet säännöt:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Sisällytä lähtötilannetiedosto projektimääritykseen ja määritä phpstan.configuration osoittamaan siihen:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Seuraava suoritus ilmoittaa [OK] No errors, ja tallennetut löydökset hyväksytään, mutta uudet virheet aiheuttavat edelleen epäonnistumisen. Jos käytät esiasetusta base tai theme, määritä lisäksi level: max kohdan parameters alla tiedostossa phpstan.neon: kanoninen komento asettaa tämän tason itse vain, kun projektimääritystä ei ole mukana.
Estä commitit analyysin perusteella
Kun "githooks": { "commit": true } on määritetty tiedostossa blockstudio.json, synkronoi hallittu koukku kerran riippuvuuksien asennuksen jälkeen:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Komento kirjoittaa koukun hakemistoon, joka kuuluu Git-järjestelmälle, määrittää core.hooksPath osoittamaan siihen ja ketjuttaa sen aiemmin määritettyyn esicommit-koukkuun. Koukun ainoa toiminto on suorittaa vendor/bin/blockstudio-phpstan -- --no-progress projektin juurihakemistosta: se ei muotoile koodia eikä tee muutoksia. Aiemmin rikotun mallipohjan commitoiminen pysähtyy analyysiin:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Aseta commit arvoksi false ja suorita sync uudelleen tai palauta aiempi koukkupolku komennolla vendor/bin/blockstudio-githooks remove.
Vain Blockstudio-komennon luomat tiedostot poistetaan.
Luo projektin sopimus
Analyysi kertoo agentille jälkikäteen, mitä se teki väärin. AGENTS.md kertoo sen etukäteen: mistä lohkot ja sivut löytyvät, miten kentät siirtyvät mallipohjiin, mitkä ominaisuudet ovat käytössä ja mitä valittu esiasetus hylkää.
blockstudio-agents luo tämän dokumentin suoraan projektin tiedoista:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Tämän oppaan teeman luoma tiedosto alkaa näin:
# 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.
Jokainen rivi perustuu johonkin kolmesta lähteestä. Projektin tiedostot määrittävät projektin tyypin, määrät, hakemistot, nimiavaruudet ja mallipohjakielet. blockstudio.json määrittää käytössä olevat ominaisuudet, joten commit-koukku näkyy “Enabled features” -osiossa ja vendor/bin/blockstudio-githooks sync “Commands” -osiossa vain, koska githooks.commit on määritetty. Valittu esiasetus määrittää oikeellisuutta käsittelevän osion, joka luetaan esiasetustiedostoista kerros kerrallaan:
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.
Pidä ajan tasalla
Sopimus vanhenee, kun määritys muuttuu. Kun otat Tailwind-ominaisuuden käyttöön tiedostossa blockstudio.json, tarkistustila huomaa sen:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Komento päättyy koodiin 1, joten sitä voi käyttää CI-vaiheena analyysin rinnalla. Tiedoston luominen uudelleen lisää ominaisuuden “Tailwind CSS” ja komennon wp bs tailwind compile.
Uudelleenluomisen säilyttämät muistiinpanot
Tiedosto päättyy muistiinpanoalueeseen. Sen merkkien välissä oleva sisältö säilyy tavu tavulta jokaisessa uudelleenluonnissa. Siksi sinne kannattaa tallentaa projektia koskeva tieto, jota ei voi päätellä tiedostoista:
## 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 -->
Generaattori ei koskaan korvaa tiedostoa, jota se ei ole luonut. Jos suoritat sen käsin kirjoitetulle AGENTS.md-tiedostolle, se kieltäytyy ja päättyy koodiin 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Jos haluat säilyttää käsin kirjoitetun tekstin, kopioi se talteen, suorita komento --force-valinnalla ja liitä teksti muistiinpanoalueeseen. Muut valinnat ovat --root, --config, --output ja --stdout, joka tulostaa sopimuksen tallentamisen sijaan.
Muutokset versiossa Blockstudio 7.7
Versio 7.7 säilyttää tässä kuvatut komennot, esiasetukset ja poistumiskoodit. Opasta laadittaessa havaittiin kaksi eroa: $a ei enää tarvitse fix-osiossa kuvattua annotaatiota, ja luotu sopimus kuvaa lohkotunnisteiden validoinnin laajemmin. Se kattaa sivujen lähteissä lohkoihin yhdistetyt HTML-elementit sekä yleiset attribuutit, joita tunniste voi välittää eteenpäin.
Seuraavat vaiheet
- PHPStan viite: kaikki säännöt, esiasetusten parametrit, kenttätyyppien rakenteet, reaaliaikaiset renderöintitarkistukset ja diagnostiikan tunnisteet.
- Tekoälyintegraatio: koodausagenttien dokumentaatiohakemisto, joka täydentää projektisi sopimusta.
- Vibe-koodaus Blockstudion avulla: työskentely koodausagenttien kanssa Blockstudio-projektissa.
- Kenttämallien keittokirja: kenttärakenteet, joiden mallipohja-avaimet analyysi tunnistaa, mukaan lukien ryhmät ja toistimet.