Pāriet uz saturu

Pārbaudītas veidnes ar PHPStan un ģenerētu AGENTS.md

Blockstudio bloks sastāv no diviem failiem, kuriem jāsaskan. block.json deklarē laukus, un veidne nolasa tos kā $a['id']. Izpildlaikā nekas neliedz veidnei nolasīt atslēgu, kas ir pārdēvēta, nav deklarēta vai uzrakstīta nepareizi. Tā vienkārši izvada tukšu virkni, un kļūda kļūst pamanāma tikai tad, kad kāds ierauga tukšu virsrakstu aktīvā lapā. Tas pats attiecas uz izvades ekranēšanu: neekranēts echo darbojas nevainojami, līdz lauka vērtībā ir marķējums.

Pakotne blockstudio/phpstan pārceļ abas problēmas uz analīzes laiku. Tā nolasa jūsu block.json failus, nosaka tajos esošo $a tipus un ziņo par neatbilstošiem veidnes nolasījumiem. Tās izvēles paplašinājumi pievieno tēmas struktūras noteikumus, ekranēšanas, kā arī JavaScript un Tailwind pārbaudes. Tajā pašā pakotnē ir divi palīgrīki: pārvaldīts pre-commit āķis, kas palaiž analīzi, un ģenerators, kas izveido AGENTS.md ar jūsu projektu aprakstošu informāciju programmēšanas aģentiem.

Šajā ceļvedī izveidosim nelielu tēmu, apzināti sabojāsim vienu tās veidni, apskatīsim analīzes izvadi, novērsīsim kļūdas un pēc tam iestatīsim komitu pārbaudi un aģenta līgumu.

Tēmas iestatīšana

Sāciet ar tēmas mapi, kurā ir style.css galvene, composer.json un viens bloks:

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

Instalējiet pakotni kā izstrādes atkarību:

Apvalks
composer require --dev blockstudio/phpstan

Tā instalē PHPStan un szepeviktor/phpstan-wordpress platformas WordPress aizstājmoduļus, un pievieno trīs izpildāmos failus direktorijai vendor/bin: blockstudio-phpstan, blockstudio-githooks un blockstudio-agents.

Pēc tam norādiet analīzei, ko palaist. Visam projektam kopīgie noklusējuma iestatījumi atrodas objekta phpstan sadaļā blockstudio.json, tāpēc interaktīvās palaišanas, CI un komitu āķis izmanto vienus un tos pašus iestatījumus:

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

extreme-theme ir stingrākais no trim statiskajiem sākotnējiem iestatījumiem. Tālāk esošajā tabulā paskaidrots, ko katrs no tiem pievieno. excludePaths neiekļauj pašas Composer failus Blockstudio skenēšanā un PHP analīzē.

Apzināti sabojājiet veidni

Hero bloks deklarē vienu lauku:

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

Veidne nolasa lauku pareizi, bet pēc tam nolasa subtitle, ko bloks nav deklarējis, un izvada to bez ekranēšanas:

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

Redaktorā un priekšgalā tiek renderēta tukša rindkopa, un kļūdas nav. Palaidiet analīzi:

Apvalks
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 beidzas ar kodu 1. Apskatīsim diagnostikas ziņojumus, sākot ar konkrētāko:

  • blockstudio.field ir veidnes noteikums. Tas atrada blakus veidnei esošo block.json, noteica tā laukus, un subtitle nav viens no tiem.
  • offsetAccess.notFound ir PHPStan pati, kas nonāk pie tāda paša secinājuma, jo paplašinājums piešķir $a konkrētu formu array{heading: string}, kas atvasināta no block.json. Katram lauka tipam atbilst PHP tips: text ir string, toggle ir bool, bet atkārtotājs ir rindu formu masīvs.
  • blockstudio.output.unescaped ir no slāņa extreme-theme. Izvadītās atribūtu vērtības jāpadod ekranēšanas funkcijai, piemēram, esc_html(), esc_attr(), esc_url() vai wp_kses_post().
  • echo.nonString izriet no nezināmās atslēgas: neesošam nobīdes laukam nav virknes tipa, ko izvadīt.
  • variable.undefined parādās tāpēc, ka PHPStan redz veidnes failu, nevis renderēšanas funkciju, kas pirms tā iekļaušanas definē $a. Šis jautājums aplūkots labošanas sadaļā.

Novērsiet kļūdu

Izlemiet, vai subtitle ir īsts lauks. Šajā gadījumā tas ir, tāpēc deklarējiet to ar default, jo tēmas slānī tas ir obligāts katram laukam:

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

Ekranējiet izvadi un deklarējiet $a ar formu, ko paplašinājums nosaka automātiski:

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

Uzrakstiet anotāciju precīzā formā. Kanoniskā komanda palaiž PHPStan līmenī max, kur brīvāka @var array<string, mixed> $a tiek noraidīta ar varTag.nativeType (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). Versijā 7.6 tā arī paplašina katra lauka tipu līdz mixed, tāpēc katrs esc_html() izsaukums ziņo par argument.type. Ziņojumā varTag.nativeType ir parādīta noteiktā forma, tāpēc tas ir arī ātrākais veids, kā atrast kopējamo anotāciju.

Blockstudio versijā 7.7 uzskata, ka $a ir definēts bloku veidnēs, tāpēc variable.undefined diagnostikas ziņojumi vairs netiek rādīti un anotācija nav obligāta. Versijā 7.7 iepriekš sabojātajā veidnē tiek ziņots par četrām kļūdām, nevis sešām, un izlabotā veidne iztur pārbaudi bez rindas @var.

Izvēlieties sākotnējo iestatījumu kopu

Instalējot pakotni, tiek aktivizēts tikai pamata paplašinājums. Ja projekts nav izvēlējies citu sākotnējo iestatījumu kopu, kanoniskā komanda palaiž base, tāpēc atkarības pievienošana pati par sevi neaktivizē stingrākus slāņus.

Sākotnējo iestatījumu kopa Ietver
base Veidnes lauku piekļuves pārbaude valodās PHP, Twig un Blade, bloku tagu pārbaudes, shēmas validācija priekš block.json, field.json un page.json, paplašinājuma JSON, db.php, rpc.php un cron.php ceļi, kā arī Settings::get() āķu nosaukumi blockstudio/*.
theme Pamata kopa un tēmas saknes un style.css galvenes, block.json deklarēti resursi, nevis manuāli pievienotas rindas, %selector% tvēruma ierobežošana style.scss, lauku noklusējuma vērtības un atkārtotāju robežvērtības.
extreme-theme Tēmas kopa un stingri PHPStan karodziņi, aizliegtie čaulas un eval() izsaukumi, neapstrādātas $wpdb rakstīšanas, izvades ekranēšana, Tailwind, JavaScript un Interactivity API pārbaudes.
wordpress-render Īpaši stingra tēmas kopa un jūsu norādīta reāllaika renderēšanas pārbaudes komanda.

Ja nav iekļauta projekta konfigurācija, kanoniskā komanda palaiž arī base un theme ar PHPStan līmeni max; extreme-theme iestata pašu max. Katrai sākotnējo iestatījumu kopas diagnostikai ir stabils identifikators blockstudio.*, kas norādīts atsaucē sākotnējo iestatījumuPHPStan uzziņa.

Tēmas un īpaši stingrais slānis pārbauda arī PHP failus. Ja laukam trūkst default un ir script.js, kas raksta konsolē, tā pati komanda ziņo:

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

Par šīm pārbaudēm tiek ziņots, izmantojot PHPStan rezultātu kešatmiņu. Pēc tikai block.json vai skripta rediģēšanas aktīvā kešatmiņa var ziņot [OK] No errors par iepriekšējo stāvokli. Pēc -- izpildiet --debug, kas apiet kešatmiņu, un tikai tad uzticieties sekmīgai pārbaudei izmaiņām, kas nav saistītas ar PHP:

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

Komandrindas opcijas un izejas kodi

Komandrindas vērtības vienai palaišanas reizei aizstāj atbilstošās blockstudio.json vērtības. Aizstāšana nozīmē aizstāšanu: padodot jebkuru --exclude, tiek atmests konfigurētais excludePaths, tāpēc, pievienojot vēl vienu, atkārtojiet vendor/**:

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

Viss, kas atrodas pēc --, tiek padots PHPStan. Ja nenorādāt savu --memory-limit, aptvere palielina PHPStan atmiņas ierobežojumu līdz 1G un izveido konfigurāciju sistēmas pagaidu direktorijā, tāpēc projektā netiek ievietots neviens ģenerēts fails. Ja analīze izdodas, programma iziet ar kodu 0; ja PHPStan ziņo par diagnostikas ziņojumiem, ar kodu 1; savukārt lietojuma, konfigurācijas vai izpildes kļūdu gadījumā — ar kodu 2.

Palaidiet to, izmantojot kanonisko komandu, nevis pievienojot phpstan/extension-installer. Sākotnējo iestatījumu kopās paplašinājums jau ir iekļauts, un, ja instalētājs ir pieejams, tas pats extension.neon tiek ielādēts divreiz: PHPStan apstājas ar ziņojumu “This file is included multiple times”, pirms tiek sākta analīze.

Pievienojiet esošu projektu

Pirmajā analīzes reizē projektā parasti tiek atrastas problēmas. Tā vietā, lai pazeminātu sākotnējo iestatījumu kopu, reģistrējiet tās pamatlīnijā, lai jaunam kodam tiktu piemēroti pilni noteikumi:

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

Iekļaujiet pamatlīniju projekta konfigurācijā un norādiet phpstan.configuration ceļu uz to:

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

Nākamajā palaišanas reizē tiek ziņots [OK] No errors, ņemot vērā reģistrētās problēmas, un visas jaunās problēmas joprojām izraisa kļūdu. Ja izmantojat sākotnējo iestatījumu kopu base vai theme, iestatiet arī level: max sadaļā parameters, failā phpstan.neon: kanoniskā komanda šo līmeni iestata pati tikai tad, ja nav iekļauta projekta konfigurācija.

Bloķējiet komitus, pamatojoties uz analīzi

Ja "githooks": { "commit": true } ir failā blockstudio.json, pēc atkarību instalēšanas vienreiz sinhronizējiet pārvaldīto āķi:

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

Komanda ieraksta āķi pašas Git direktorijā, norāda core.hooksPath uz to un izsauc iepriekš konfigurēto pre-commit āķi, ja tāds ir. Āķis izpilda tikai vendor/bin/blockstudio-phpstan -- --no-progress no projekta saknes direktorijas: bez formatētāja un bez pārrakstīšanas. Iepriekš aprakstītā kļūdainā veidne aptur komitu analīzes stadijā:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Iestatiet commit uz false un palaidiet sync vēlreiz vai izpildiet vendor/bin/blockstudio-githooks remove, lai atjaunotu iepriekšējo āķa ceļu. Tiek dzēsti tikai tie faili, ko izveidojis Blockstudio.

Ģenerējiet projekta līgumu

Analīze aģentam pēc fakta pasaka, ko tas izdarījis nepareizi. AGENTS.md to pasaka jau iepriekš: kur atrodas bloki un lapas, kā lauki nonāk veidnēs, kuras funkcijas ir iespējotas un ko noraidīs atlasītā sākotnējo iestatījumu kopa. blockstudio-agents ģenerē šo dokumentu, izmantojot pašu projektu:

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

Šajā ceļvedī aplūkotajai tēmai ģenerētā faila sākums ir šāds:

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.

Katra rinda tiek iegūta no viena no trim avotiem. Projekta faili nosaka projekta veidu, skaitu, direktorijas, nosaukumvietas un veidņu valodas. blockstudio.json nosaka iespējotās funkcijas, tāpēc komitu āķis ir sadaļā “Iespējotās funkcijas”, bet vendor/bin/blockstudio-githooks sync ir sadaļā “Komandas” tikai tāpēc, ka ir iestatīts githooks.commit. Atlasītā sākotnējo iestatījumu kopa nosaka pareizības sadaļu, kuras saturs slāni pa slānim nolasīts no sākotnējo iestatījumu kopas failiem:

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.

Uzturiet to aktuālu

Ja mainās konfigurācija, līgums noveco. Pēc Tailwind iespējošanas failā blockstudio.json pārbaudes režīms to pamana:

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

Komanda iziet ar kodu 1, tāpēc to var izmantot CI darbībā līdzās analīzei. Atkārtoti ģenerējot, tiek pievienots funkcijas ieraksts “Tailwind CSS” un komanda wp bs tailwind compile.

Piezīmes, kas tiek saglabātas pēc atkārtotas ģenerēšanas

Faila beigās ir vieta piezīmēm. Viss, kas atrodas starp tās marķieriem, tiek saglabāts baits baitā pēc katras atkārtotas ģenerēšanas, tāpēc tur ievietojiet informāciju par projektu, ko nevar iegūt no failiem:

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

Ģenerators nekad neaizstāj failu, ko tas nav izveidojis. Mēģinot to palaist pret paša rakstītu AGENTS.md, tas atsakās un iziet ar kodu 2:

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

Lai saglabātu paša rakstītu tekstu, kopējiet to citur, palaidiet ar --force un ielīmējiet piezīmju sadaļā. Pārējās opcijas ir --root, --config, --output un --stdout; šī pēdējā izvada līgumu, nevis ieraksta to failā.

Izmaiņas Blockstudio versijā 7.7

Šeit aprakstītās 7.7 pakotnes komandas, sākotnējo iestatījumu kopas un izejas kodi nav mainījušies. Veidojot šo ceļvedi, atklājās divas atšķirības: $a vairs nav vajadzīga anotācija, kā aprakstīts labošanas sadaļā, un ģenerētajā līgumā bloku tagu validācija aprakstīta plašāk, ietverot HTML elementus, kas lapu avotos piesaistīti blokiem, kā arī globālos atribūtus, ko tags var pārsūtīt.

Nākamās darbības

  • PHPStan atsauce: katrs noteikums, iepriekš iestatītais parametrs, lauka tipa struktūra, reāllaika renderēšanas zonde un diagnostikas identifikators.
  • AI Integration: kodēšanas aģentu dokumentācijas rādītājs, kas papildina jūsu projekta līgumu.
  • Vibecoding ar Blockstudio: darbs ar kodēšanas aģentiem Blockstudio projektā.
  • Field Patterns Cookbook: lauku struktūras, kuru veidņu atslēgas analīze saprot, tostarp grupas un atkārtotāji.