Preskoči na vsebino

Preverjene predloge z PHPStan in ustvarjenim AGENTS.md

Blok Blockstudio sestavljata dve datoteki, ki se morata ujemati. Datoteka block.json določa polja, predloga pa jih bere kot $a['id']. Med izvajanjem nič ne prepreči predlogi, da bi prebrala ključ, ki je bil preimenovan, nikoli ni bil določen ali je napačno črkovan. Preprosto izriše prazen niz, napaka pa se pokaže šele, ko kdo opazi prazen naslov na objavljeni strani. Enako velja za ubežanje izhoda: neubežani echo deluje brezhibno, dokler vrednost polja ne vsebuje označevanja.

Paket blockstudio/phpstan obe težavi prestavi v čas analize. Prebere vaše datoteke block.json, iz njih določi vrste za $a in opozori na branja v predlogah, ki se ne ujemajo. Izbirne prednastavitve dodajo pravila za strukturo teme, ubežanje ter preverjanja JavaScript in Tailwind. Paket vključuje tudi spremljevalni orodji: upravljan kavelj pred potrditvijo, ki zažene analizo, in generator, ki ustvari datoteko AGENTS.md z opisom vašega projekta za programske agente.

Ta vodnik sestavi majhno temo, namerno pokvari eno od njenih predlog, pregleda izpis analize, odpravi napako, nato pa nastavi preverjanje potrditve sprememb in pogodbo za agenta.

Nastavitev teme

Začnite z mapo teme, ki vsebuje glavo style.css, datoteko composer.json in en blok:

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

Namestite paket kot odvisnost za razvoj:

Lupina
composer require --dev blockstudio/phpstan

Vključi PHPStan in ogrodja WordPress iz szepeviktor/phpstan-wordpress ter namesti tri izvršne datoteke v vendor/bin: blockstudio-phpstan, blockstudio-githooks in blockstudio-agents.

Nato določite, kaj naj analiza zažene. Privzete nastavitve za celoten projekt so v objektu phpstan v blockstudio.json, zato interaktivni zagoni, CI in kavelj ob potrditvi sprememb uporabljajo iste nastavitve:

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

extreme-theme je najstrožja od treh statičnih prednastavitev. V spodnji tabeli je pojasnjeno, kaj doda vsaka od njih. excludePaths izloči lastne datoteke Composer iz pregleda Blockstudio in analize PHP.

Namerno pokvarite predlogo

Blok hero določa eno samo polje:

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

Predloga polje pravilno prebere, nato pa prebere subtitle, ki ga blok ni določil, in ga izpiše brez ubežanja:

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

V urejevalniku in na spletnem mestu se izriše prazen odstavek, napake pa ni. Namesto tega zaženite analizo:

Lupina
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

Ukaz se konča z vrednostjo 1. Diagnostiko preglejte od najbolj specifične navzdol:

  • blockstudio.field je pravilo predloge. Ob predlogi je našlo block.json, razrešilo njegova polja in ugotovilo, da subtitle ni med njimi.
  • offsetAccess.notFound je PHPStan sam prišel do enakega sklepa, saj razširitev določa konkretno obliko $a kot array{heading: string}, izpeljano iz block.json. Vsaka vrsta polja se preslika v vrsto PHP: text je string, toggle pa bool; ponavljalnik je polje oblik vrstic.
  • blockstudio.output.unescaped izhaja iz plasti extreme-theme. Ponovljene vrednosti atributov je treba obdelati s funkcijo za ubežanje, kot so esc_html(), esc_attr(), esc_url() ali wp_kses_post().
  • echo.nonString izhaja iz neznanega ključa: neobstoječi odmik nima vrste niza, ki bi jo bilo mogoče ponoviti.
  • variable.undefined se pojavi, ker PHPStan vidi datoteko predloge, ne pa funkcije za izris, ki določa $a, preden jo vključi. Razdelek o odpravi težave to pojasnjuje.

Odprava napake

Odločite se, ali je subtitle pravo polje. Tukaj je, zato ga določite z default, saj plast teme to zahteva za vsako polje:

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

Ubežite izhod in določite $a z obliko, ki jo sklepa razširitev:

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>
Lupina
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [OK] No errors

Opombo zapišite v natančni obliki. Kanonični ukaz zažene PHPStan na ravni max, kjer je ohlapnejši @var array<string, mixed> $a zavrnjen z varTag.nativeType (»PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}«). V različici 7.6 prav tako razširi vsako polje v mixed, zato vsak klic esc_html() javi argument.type. Sporočilo varTag.nativeType izpiše izpeljano obliko, zato je tudi najhitrejši način, da najdete opombo, ki jo lahko kopirate.

V različici 7.7 Blockstudio obravnava $a kot določeno znotraj predlog blokov, zato diagnostika variable.undefined izgine, opomba pa ni več obvezna. V primerjavi z različico 7.7 pokvarjena predloga zgoraj prikaže štiri napake namesto šestih, popravljena predloga pa prestane preverjanje brez vrstice @var.

Izbira prednastavitve

Namestitev paketa omogoči samo osnovno razširitev. Kanonični ukaz zažene base, razen če projekt izbere drugo prednastavitev, zato dodajanje odvisnosti samo po sebi ne vklopi strožjih plasti.

Prednastavitev Dodaja
base Dostop do polj predlog v PHP, Twig in Blade, preverjanja oznak blokov, preverjanje sheme za block.json, field.json, page.json, razširitve JSON, db.php, rpc.php in cron.php, poti Settings::get() ter imena kavljev blockstudio/*.
theme Osnovna prednastavitev ter koreni teme in glave style.css, sredstva, določena v block.json namesto ročnega dodajanja v čakalno vrsto, omejitve %selector% v style.scss, privzete vrednosti polj in meje ponavljalnikov.
extreme-theme Prednastavitev teme ter stroge zastavice PHPStan, zavrnjeni klici lupine in eval(), neposredni zapisi $wpdb, ubežanje izhoda, Tailwind, JavaScript in preverjanja API Interactivity.
wordpress-render Izjemno stroga prednastavitev teme in živa preizkusna izvedba izrisa, ki jo podate kot ukaz.

Ko konfiguracija projekta ni vključena, se kanonični ukaz izvaja tudi pri ravni PHPStan max z base in theme; extreme-theme sam nastavi max. Vsaka prednastavljena diagnostika ima stabilni identifikator blockstudio.*, naveden v PHPStanreferenčnem priročniku.

Plasti teme in izjemno stroge nastavitve preverjajo tudi PHP datoteke. Če polju manjka njegov default, script.js pa beleži v konzolo, isti ukaz javi:

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

Ta preverjanja se poročajo prek predpomnilnika rezultatov PHPStan. Če uredite samo block.json ali skript, lahko ogret predpomnilnik za staro stanje javi [OK] No errors. Po -- podajte --debug, ki obide predpomnilnik, preden zaupate uspešnemu zagonu po spremembah, ki niso PHP:

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

Možnosti ukaza in izhodne kode

Vrednosti ukazne vrstice za en zagon nadomestijo ustrezne vrednosti blockstudio.json. Nadomestijo jih v celoti: če podate katerikoli --exclude, se zavrže nastavljeni excludePaths, zato pri dodajanju ponovite vendor/**:

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

Vse, kar sledi --, se posreduje programu PHPStan. Ovoj zviša omejitev pomnilnika za PHPStan na 1G, razen če podate svoj --memory-limit, konfiguracijo pa sestavi v začasnem sistemskem imeniku, tako da v projektu ne nastane nobena ustvarjena datoteka. Konča se z vrednostjo 0, če analiza uspe, 1, če PHPStan javi diagnostiko, in 2 pri napakah uporabe, konfiguracije ali izvajanja.

Zaženite ga prek kanoničnega ukaza, namesto da dodate phpstan/extension-installer. Prednastavitve razširitev že vključujejo, ob nameščenem namestitvenem programu pa se ista extension.neon naloži dvakrat: PHPStan se ustavi s sporočilom »This file is included multiple times« še pred začetkom analize.

Uporaba v obstoječem projektu

Pri prvi analizi projekta se običajno najdejo težave. Namesto da znižate raven prednastavitve, jih zabeležite v osnovnem stanju, tako da bodo za novo kodo veljala vsa pravila:

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

Osnovno stanje vključite v konfiguracijo projekta in usmerite phpstan.configuration nanj:

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

Naslednji zagon javi [OK] No errors z zabeleženimi ugotovitvami, nove napake pa še vedno povzročijo neuspeh. Pri prednastavitvi base ali theme nastavite tudi level: max pod parameters v phpstan.neon: kanonični ukaz to raven nastavi sam samo, če konfiguracija projekta ni vključena.

Preverjanje potrditev sprememb z analizo

Ko je "githooks": { "commit": true } v blockstudio.json, po namestitvi odvisnosti enkrat sinhronizirajte upravljani kavelj:

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

Ukaz zapiše kavelj v imenik Git in nastavi, da ga uporablja core.hooksPath, nato pa doda še morebitni predhodno konfigurirani kavelj pred potrditvijo sprememb. Kavelj iz korena projekta zažene vendor/bin/blockstudio-phpstan -- --no-progress in ničesar drugega: brez oblikovalnika, brez prepisov. Če poskusite potrditi pokvarjeno predlogo iz prejšnjega primera, se postopek ustavi pri analizi:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Nastavite commit na false in znova zaženite sync ali pa za obnovitev prejšnje poti do kavlja zaženite vendor/bin/blockstudio-githooks remove. Izbrišejo se samo datoteke, ki jih je zapisal Blockstudio.

Ustvarjanje projektne pogodbe

Analiza agentu naknadno pove, kaj je naredil narobe. AGENTS.md ga seznani vnaprej: kje so bloki in strani, kako polja dosežejo predloge, katere funkcije so omogočene in kaj bo izbrana prednastavitev zavrnila. blockstudio-agents ustvari ta dokument iz samega projekta:

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

Za temo iz tega vodnika se ustvarjena datoteka začne takole:

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.

Vsaka vrstica izhaja iz enega od treh virov. Datoteke projekta podajo vrsto projekta, števila, imenike, imenske prostore in jezike predlog. blockstudio.json določa omogočene funkcije, zato je kavelj za potrditve sprememb naveden pod »Omogočene funkcije«, vendor/bin/blockstudio-githooks sync pa pod »Ukazi« samo zato, ker je nastavljen githooks.commit. Izbrana prednastavitev določa razdelek o pravilnosti, ki se bere iz datotek prednastavitve plast za plastjo:

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.

Posodabljanje

Pogodba zastara, ko se spremeni konfiguracija. Ko omogočite Tailwind v blockstudio.json, to zazna način preverjanja:

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

Konča se z vrednostjo 1, zato ga lahko uporabite kot korak CI poleg analize. Če dokument znova ustvarite, se dodata vnos funkcije »Tailwind CSS« in ukaz wp bs tailwind compile.

Opombe, ki se ohranijo pri ponovnem ustvarjanju

Datoteka se konča z območjem za opombe. Vsebina med njegovimi označevalniki se pri vsakem ponovnem ustvarjanju ohrani povsem enaka, zato vanj sodijo projektno znanje, ki ga ni mogoče izpeljati iz datotek:

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

Generator nikoli ne prepiše datoteke, ki je ni ustvaril. Če ga zaženete za ročno napisano datoteko AGENTS.md, zavrne postopek in se konča z vrednostjo 2:

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

Če želite ohraniti ročno napisano besedilo, ga shranite drugam, zaženite z --force in ga prilepite v območje za opombe. Druge možnosti so --root, --config, --output in --stdout, ki izpiše pogodbo namesto, da bi jo zapisal.

Kaj se spremeni v različici Blockstudio 7.7

Paket 7.7 ohranja tukaj opisane ukaze, prednastavitve in izhodne kode. Med pripravo tega vodnika za to različico sta se pokazali dve razliki: $a ne potrebuje več opombe, kot je opisano v razdelku o popravku, ustvarjena pogodba pa širše opisuje preverjanje oznak blokov in zajema elemente HTML, preslikane v bloke v virih strani, ter globalne atribute, ki jih oznaka lahko posreduje naprej.

Naslednji koraki