Ugrás a tartalomhoz

PHPStan

A blockstudio/phpstan bővítmény statikus elemzést biztosít Blockstudio projektekhez. Elemzéskor ellenőrzi a blokksablonokat, sémafájlokat, beállítási útvonalakat és a hookneveket, így még futás előtt felderíti a hibákat.

Telepítés

Shell
composer require --dev blockstudio/phpstan

A 7.7-es sablontípusok és a kibővített blokkcímke-ellenőrzések használatához legalább blockstudio/phpstan 0.1.9 és PHPStan 2.1.47 szükséges. Frissítse a csomagot a bővítménytől külön:

Shell
composer require --dev blockstudio/phpstan:^0.1.9

A bővítmény automatikusan felismerhető a PHPStan bővítménytelepítőjén keresztül. Nincs szükség kézi konfigurációra.

Mit ellenőriz

Sablonmezők elérése

Ha egy PHP fájl egy block.json mellett található, a bővítmény minden $a['key'] hozzáférést ellenőriz a blokk deklarált attribútumai alapján.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

A bővítmény tudja, hogy a Blockstudio definiálja a $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview és a szigetek változóit, mielőtt sablont illeszt be. Ezért a közvetlen olvasásokat, például a $a['title'] kifejezést nem jelzi potenciálisan definiálatlanként, a $a típusát pedig a sablon melletti block.json alapján határozza meg. A mezőszerkezet szűkítés után is megmarad, ezért a $a['label'] ?? '', isset( $a['cta']['target'] ) és $a['cta']['title'] !== null megtartja a deklarált mezőtípusokat; ha egy sablon maga rendeli hozzá az értéket a $a elemhez, annak típusa a hozzárendelt típus marad. Ne adjon hozzá /** @var array<string, mixed> $a */ docblockot: ez nyitott tömbre cseréli a mezőszerkezetet.

A mezőkulcsok a Blockstudio futásidejű lapítási szabályait követik. Az tabs és a névtelen group konténerek id nélkül csak megjelenítési célúak, ezért a gyermekmezőik a szülő hatókörében maradnak. A névvel rendelkező csoport a csoportazonosítóval egészíti ki a gyermekkulcsokat:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Újrafelhasználható egyéni mezők

A fájlalapú custom/* hivatkozások feloldása megelőzi a sablonkulcsok és tömbstruktúrák ellenőrzését. A bővítmény beolvassa a megfelelő field.json fájlt, majd ugyanazokat a idStructure, overrides, beágyazott hivatkozási, csoport-, lap- és ismétlőszabályokat alkalmazza, mint a Blockstudio:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/mytheme/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "id": "title" }
        }
      }
    ]
  }
}

Az így létrejövő sablonkulcsok: title és hero_description. A rendszer felismeri őket a következőkben: PHP, Twig, Blade, blokkcímkék és kikövetkeztetett attribútumstruktúrák.

A hiányzó, nem egyértelmű, érvénytelen vagy ciklikus fájlalapú definíciók külön blockstudio.customField.* hibát eredményeznek. A blokk függő kulcsainak ellenőrzése ilyenkor kimarad, így egy feloldatlan definíció nem okoz további, ismeretlen mezőkre vonatkozó téves hibákat.

A kizárólag futásidőben, a blockstudio/fields PHP szűrőn keresztül regisztrált definíciók nem következtethetők ki statikus elemzéssel. Használjon field.json definíciót, ha a mezőnek statikusan ellenőrzött sablonkulcsokat kell biztosítania.

Twig sablon elérése

A Twig sablonokat a rendszer automatikusan átvizsgálja. Nincs szükség annotációra.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Blade sablon elérése

A Blade sablonokat ugyanígy vizsgálja át a rendszer.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Blokkcímkék ellenőrzése

A blokkcímkék ellenőrzése ott történik, ahol a Blockstudio beolvassa őket: a <bs:> és <block> címkéknél, a blockTags.prefixes elemben konfigurált előtagcímkéknél (például <acme-card>, a futásidőhöz hasonló névtérsorrendben feloldva), valamint az aliascímkéknél, a PHP, Twig és Blade blokksablonokban és az oldalelrendezésekben. A pages/ alatti oldalak forrásait (index.php, index.html, index.twig, index.blade.php) szintén ellenőrzi, beleértve a projekt által blokkokhoz rendelt HTML elemeket is. A beépített UI blokkok akkor ismertek, ha a ui.enabled be van kapcsolva.

HTML
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->

Az attribútum akkor fogadható el, ha a blokk mezőként deklarálja (az egyéni mezőket és azokat a mezőket is beleértve, amelyeket egy blokktípusú mező a saját idStructure eleme alatt továbbít), vagy ha a Blockstudio továbbítja a blokk gyökéreleméhez: data-*, aria-*, id, style, role, title, lang, dir, hidden és tabindex. A sablonokban minden html-* attribútum továbbításra kerül; az oldalforrásokban az html- előtag csak a továbbított attribútumok egyikét jelöli. Minden más attribútumot, különösen a nem deklarált class értéket, jelez a rendszer, mert a Blockstudio eltárolja, de soha nem jeleníti meg.

A futtatókörnyezet az elemleképezéseket és címkealiasokat a PHP szűrőkben regisztrálja, amelyeket a statikus elemzés nem tud kiértékelni, ezért az elemzés a blockstudio.json alapján olvassa be őket. A scanPhp más projektbeli PHP címkéit is ellenőrzi, például a modulok komponensjelöléseit, anélkül, hogy ott ismeretlen blokkokat jelezne:

JSON
{
  "phpstan": {
    "blockTags": {
      "elements": {
        "section": "theme/section",
        "h2": "theme/heading",
        "div": [
          { "attribute": "width", "block": "theme/row" },
          "theme/div"
        ]
      },
      "aliases": { "theme-button": "bsui/button" },
      "scanPhp": true
    }
  }
}

Egy elem blokknevet vagy sorrendben kipróbált szabályokat rendelhet hozzá: az első olyan szabály érvényesül, amelynek attribútumát az elem tartalmazza; az egyszerű blokknevek pedig mindig illeszkednek. A projekthez nem rendelt elemek megtartják az alapszintű blokkjukat, és kimaradnak az ellenőrzésből. A diagnosztikai üzenetek a blockstudio.blockTag.unknown, blockstudio.blockTag.attribute és blockstudio.blockTag.class értékeket használják.

Adatbázisrekordok típusai

A Db::get() a db.php séma alapján típusos példányt ad vissza. A rekordok szerkezete automatikusan kikövetkeztethető.

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // string
echo $record['name'];  // string|null (optional field)
echo $record['typo'];  // Error: Offset 'typo' does not exist

A kötelező mezők nem lehetnek null értékűek. Az opcionális mezők típusa type|null. Egy id mező (int) mindig jelen van. Ugyanez a típusozás működik a PHP-natív Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field builder szintaxissal is.

Beállítási útvonalak ellenőrzése

A Settings::get() útvonalakat a rendszer az ismert beállítási séma alapján ellenőrzi.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Hooknevek ellenőrzése

A Blockstudio szűrő- és műveleti hookneveket a rendszer ellenőrzi.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

A dinamikus beállítási hookok, például a blockstudio/settings/tailwind/enabled, mindig engedélyezettek. A nem blockstudio hookokat a rendszer figyelmen kívül hagyja.

Sémaellenőrzés

A bővítmény ellenőrzi a projekt minden Blockstudio sémájú fájlját.

block.json:

  • Hiányzó name mező
  • Hiányzó type mező
  • Hiányzó id olyan értékmezőknél, amelyekhez ez szükséges
  • Ismeretlen mezőtípusok
  • A mezőtípus által nem elfogadott mezőtulajdonságok, például "translat" használata "translate" helyett; javaslatként a rendszer a legközelebbi ismert tulajdonságot adja meg
  • select/radio/checkbox options vagy populate nélkül
  • Duplikált mezőazonosítók
  • tabs mező egy ismétlőben, közvetlenül vagy egy csoporton belül, id nélkül
  • Érvénytelen pluginDependencies deklarációk

A konténermezők, például a group és a tabs, valamint a custom/* mezőhivatkozások elhagyhatják a id értéket, ha csak más mezőket bővítenek ki vagy csomagolnak be.

A mezőtulajdonságokat a rendszer összeveti azokkal a tulajdonságokkal, amelyeket a schemas/block.json az egyes beépített mezőtípusokhoz deklarál, valamint azokkal, amelyeket minden mező elfogad. A custom/* hivatkozásokra jellemző burkoló tulajdonságok és a projektben definiált, névtérrel ellátott mezőtípusok kívül esnek ezen az ellenőrzésen. A meglévő mezőtípus- és egyéni hivatkozás-ellenőrzések továbbra is érvényesek. Az azonosítók: blockstudio.blockJson.property és blockstudio.fieldJson.property.

Ez a tulajdonságneveket ellenőrzi, nem csupán az értékeiket: a minimized érvényes egy ismétlő mezőn, de szövegmezőn hibajelzést ad. A bővítmény futásidejű viselkedése nem változik. Ha egy projekt szándékosan saját metaadatokat rendel a beépített mezőkhöz, csak ezeket a találatokat tiltsa le, a többi alakellenőrzés letiltása nélkül:

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Az újrafelhasználható field.json belsejében lévő beépített mezők ellenőrzése akkor is megtörténik, ha egy custom/* hivatkozásnak saját burkoló beállításai vannak. A bővítményfájlok kívül esnek e tulajdonságnév-diagnosztika hatókörén; a bővítményspecifikus set szabályok továbbra is érvényesek.

field.json (újrafelhasználható egyéni mezők):

  • Hiányzó name
  • Hiányzó vagy üres attributes
  • Érvénytelen attribútumobjektumok vagy hiányzó mező-type
  • Hiányzó id az azt igénylő értékmezőkön
  • Ismeretlen mezőtípusok
  • Olyan mezőtulajdonságok, amelyeket a mezőtípus nem fogad el
  • tabs mező ismétlő mezőn belül, közvetlenül vagy egy csoportban, id nélkül
  • Hiányzó, kétértelmű, érvénytelen vagy ciklikus beágyazott custom/* hivatkozások

JSON bővítmény (blokkbővítmények a extensions/ fájlban):

  • Hiányzó name (célelem)
  • Hiányzó blockstudio kulcs
  • Hiányzó blockstudio.extend kulcs

page.json (fájlalapú oldalak):

  • Hiányzik: title
  • Hiányzik: slug
  • Érvénytelen postStatus értékek

db.php:

  • Hiányzik a fields tömb
  • Érvénytelen mezőtípusok
  • A régi tömböket és a Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field formátumot is támogatja

rpc.php:

  • Érvénytelen HTTP metódusok
  • Hibás public érték (csak true, false vagy 'open' lehet)
  • A régi tömböket és az attribútumokkal ellátott objektumok visszaadását is támogatja

cron.php:

  • Hiányzik a schedule a konfigurált feladatoknál
  • Hiányzik a callback a konfigurált feladatoknál
  • A régi tömböket és az attribútumokkal ellátott objektumok visszaadását is támogatja

blockstudio.json:

  • Rövidített logikai értékek, például "tailwind": true (a beágyazott objektumformátumot kell használni: {"enabled": true, "config": ""})

Konfiguráció

A bővítmény alapértelmezés szerint megkeresi az elemzett projekt Blockstudio fájljait. Ha a projekt a projektgyökéren kívüli könyvtárból származó blokkokat vagy újrafelhasználható mezőket használ, adja hozzá a könyvtár elérési útját a blockstudioScanRoots beállításhoz. Az útvonalon a rendszer a block.json és field.json definíciókat is keresi, így a külső blokkcímkék és egyéni mezőik együtt ellenőrizhetők.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

A fájlok kihagyásához használja a PHPStan szabványos excludePaths konfigurációját.

Elemzési presetek

Az automatikusan felismert bővítmény marad a kompatibilitást biztosító alap. A Blockstudio 7.6 bekapcsolható rétegeket ad hozzá a meglévő projektek módosítása nélkül:

Preset Működés
base.neon Meglévő séma-, sablon-, hook-, beállítás- és API-elemzés.
theme.neon Az alap kiegészítve WordPress témagyökerekkel, stílusfejlécekkel, Blockstudio-eszközökkel, szelektorhatókörökkel, alapértelmezett mezőértékekkel és az ismétlők korlátaival.
extreme-theme.neon A téma kiegészítve PHPStan max-, nem biztonságos PHP-, kimenetkódolási, Tailwind-, JavaScript- és Interactivity API-ellenőrzésekkel.
wordpress-render.neon Az extrém téma kiegészítve a hívó által megadott, éles WordPress renderelési próbával.

A blockstudio/phpstan telepítése csak az alapbővítményt engedélyezi. Vegyen fel egy bekapcsolható réteget a meglévő PHPStan konfigurációba:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

A blockstudioThemeExcludePaths vezérli a témavizsgálót. A PHPStan szabványos excludePaths beállítása önállóan vezérli a PHP elemzését.

A kanonikus parancs phpstan.excludePaths beállítása a blockstudio.json fájlban (és annak --exclude kapcsolója) mindkét réteget konfigurálja. A relatív minták minden megadott gyökérhez képest oldódnak fel, ezért az olyan bejegyzések, mint a vendor/**, az PHPStan elemzését és a Blockstudio projektvizsgálatát egyaránt korlátozzák.

Az egyetlen könyvtárat megadó minta, például a _dist/** vagy a node_modules/**, minden előfordulási helyén kizárja azt a könyvtárat, nem csak a témagyökér mellett. A perjelet tartalmazó minta, például a assets/*/docs/**, a gyökérhez kötve marad. A generált blokkeszközök minden blokkon belül egy _dist könyvtárban találhatók, ezért az egykönyvtáros formával zárható ki a lefordított kimenet az elemzésből.

Kanonikus parancs

A csomag elemző futtatható fájlként telepíti a vendor/bin/blockstudio-phpstan eszközt. Ha a projekt nem választ másikat, a base presetet futtatja, ezért a csomag telepítése önmagában soha nem engedélyezi a téma- vagy extrém téma-rétegeket:

Shell
vendor/bin/blockstudio-phpstan --root . -- --no-progress

A presetek magukban foglalják a bővítményt. Ne adja hozzá a phpstan/extension-installer elemet ahhoz a projekthez, amely a kanonikus parancsot futtatja: ha a telepítő jelen van, a extension.neon kétszer töltődik be, és a PHPStan leáll a „This file is included multiple times” hibaüzenettel, mielőtt bármit elemezne.

A parancs alapértelmezés szerint PHPStan beállítást használ 1G memóriakorláttal, így az Composer által kezelt WordPress projektekre nem vonatkozik a szokásos 128M CLI korlát. Felülbíráláshoz adjon meg explicit PHPStan kapcsolót a -- után, például: -- --memory-limit=512M --no-progress.

Elemzés bevezetése meglévő projekten

Az első elemzés általában találatokat jelez egy olyan projektnél, amelyet korábban még nem elemeztek. A preset enyhítése helyett hozzon létre egy PHPStan alapállapotot, és állítsa be az phpstan.configuration értékét egy olyan projektkonfigurációra, amely tartalmazza azt. Így az új kódra a teljes preset vonatkozik, miközben a rögzített találatok nem zavarják a munkát:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "phpstan": {
    "configuration": "phpstan.neon"
  }
}

Tartsa meg a level sort a base és theme preseteknél. A kanonikus parancs csak akkor állítja be számukra a max szintet, ha nincs projektkonfiguráció megadva; PHPStan szint nélkül a parancs „No rules detected” hibaüzenettel leáll. A extreme-theme preset maga állítja be a max szintet.

A relatív útvonalak feloldása a blockstudio.json helyétől indul. A kanonikus parancs és a felügyelt commit hook is betölti ezt a fájlt, így a hook az új találatokat akkor is megakadályozza, ha a korábbi hátralékot még nem javították ki.

A projektre érvényes parancsalapértékeket tartsa a blockstudio.json fájlban:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

A relatív gyökerek feloldása az azokat deklaráló fájl helyétől indul. Az explicit CLI értékek felülírják a megfelelő JSON értékeket. Alternatív konfigurációs forrás megadásához használja a --blockstudio-json path/to/project.json kapcsolót. A hibás JSON, a nem támogatott phpstan kulcsok, az érvénytelen értékek és a hiányzó explicit forrás kiszámítható módon, 2 kilépési kóddal állítja le a futást.

Válasszon másik presetet, adjon meg projektkonfigurációt, vegyen fel ismételhető gyökereket és kizárásokat, vagy kérje meg a PHPStan eszközt a következőre: JSON.

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

A wrapper a rendszer ideiglenes könyvtárában állítja össze a konfigurációt, majd kilépéskor törli. Soha nem ír generált konfigurációt, alapállapotot, hookot vagy gyorsítótárat az elemzett projektbe. A hívók továbbra is beállíthatják a PHPStan szokásos gyorsítótárát.

A kilépési kódok jelentése:

  • 0, ha az elemzés sikeres
  • 1, ha a PHPStan diagnosztikai üzeneteket jelez
  • 2 érvénytelen használat, konfiguráció vagy folyamatvégrehajtás esetén

Kezelt commit hook

Az extrém téma elemzésének adattári commitfeltételként való engedélyezéséhez kapcsolja be a blockstudio.json fájlban a Blockstudio által kezelt hookot:

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

Szinkronizálja függőségek telepítése vagy a beállítás módosítása után:

Shell
vendor/bin/blockstudio-githooks sync

A parancs a generált pre-commit hookot és a tulajdonosi rekordot a Git közös könyvtárába írja, a core.hooksPath értékét pedig a felügyelt hookkönyvtárra állítja, majd biztonságosan láncba fűzi a korábban beállított pre-commit hookot. Az ismételt szinkronizálások csak a generált fájlt frissítik, így a csomagfrissítések idempotensek.

Állítsa a commit értékét false-re, távolítsa el ezt a beállítást vagy a blockstudio.json fájlt, majd futtassa a sync parancsot a rögzített hookútvonal visszaállításához és csak a Blockstudio által kezelt fájlok törléséhez. Ezt is futtathatja:

Shell
vendor/bin/blockstudio-githooks remove

A felhasználó tulajdonában lévő fájlokat a rendszer soha nem írja felül és nem törli. Ha valaki a Blockstudio engedélyezése után módosítja a core.hooksPath beállítást, eltávolításkor az újabb érték megmarad. A generált hook támogatja az összekapcsolt Git checkoutokat és a szóközt tartalmazó útvonalakat: commitkor feloldja az aktív adattár és projektgyökér helyét. A kanonikus parancsot ebből a gyökérből futtatja, így ugyanaz a phpstan objektum vezérli az interaktív futtatásokat és a commitokat, generált argumentumok ismétlése nélkül.

A hook csak a vendor/bin/blockstudio-phpstan parancsot futtatja. A Blockstudio nem futtat formázót, és a hook soha nem írja át a projekt fájljait. A hiányzó függőségek és az elemzési hibák egyértelmű hibaüzenettel megakadályozzák a commitot.

Élő WordPress renderelés

Az élő réteg szándékosan explicit. A hívó kezeli a WordPress környezetet, és argv-tömböt ad meg:

Shell
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

A parancs shell nélkül fut, és egyetlen JSON objektumot kell kiírnia:

JSON
{"ok":true}

A próba célzott hibát is jelezhet:

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

A nem nulla kilépési kód, az időtúllépés, a hibás JSON és a ok: false eredménye blockstudio.wordpress.render.

A blockstudio.javascript.domContract olyan [data-*] attribútumválasztót jelez, amelyet egy szkript átad a querySelector(), querySelectorAll(), closest() vagy matches() számára, miközben az elemzett jelölésben egyetlen elem sem rendelkezik ezzel az attribútummal. A jelölés magában foglalja az összes PHP, Twig, Blade és HTML fájlt, valamint az elemzett gyökérkönyvtárak alatti minden React .tsx és .jsx komponenst, a kizárt útvonalak kivételével. A rendszer feldolgozza a komponenseket: az JSX attribútumnevek is számítanak, ahogy az objektumliterálok karakterlánckulcsai is. Ezért az elemre terített attribútumobjektum teljesíti a választót, az osztálynevek és más attribútumértékek viszont nem.

Az interaktivitási API ellenőrzések ugyanazokat a React komponenseket olvassák be. A JSX elemen lévő data-wp-interactive névtér sablonhivatkozásnak számít a blockstudio.interactivity.orphan számára, a benne lévő data-wp-* direktívák pedig a legközelebbi körülvevő névtérhez oldódnak fel, vagy az értékben szereplő namespace:: előtaghoz. A statikus karakterlánc-értékű direktíváknak, akár JSX attribútumként, akár egy attribútumobjektum karakterlánckulcsaként vannak megadva, létező tárolókezelőkre és útvonalakra kell hivatkozniuk (blockstudio.interactivity.handler, blockstudio.interactivity.binding), a tárolókód pedig nem módosíthatja azokat az attribútumokat és osztályokat, amelyekhez kötve van (blockstudio.interactivity.derivedState). A React escape-eli az attribútumértékeket, ezért az összetevőben lévő data-wp-context nem kap hibajelzést, a dinamikus értékek ellenőrzése pedig elmarad. A bsui/ alatti névterek a csomagban lévő UI blokkokhoz tartoznak; ezek tárolóit az elemzett gyökérkönyvtárakon kívül szállítják a Blockstudio részeként, így soha nem minősülnek gazdátlannak.

Diagnosztikai azonosítók

Az új presetdiagnosztikák stabil blockstudio.* azonosítókat használnak:

  • Témaszerkezet: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Eszközök és mezők: blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP: blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind: blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript: blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • Interaktivitás: blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

Teljesítmény

A vizsgáló hagyományos, materializált könyvtárakat fogad el, deduplikálja a gyökereket, kihagyja a függőségi, build- és gyorsítótár-fákat, memóriában gyorsítótárazza a fájlbeolvasásokat, és kiszámítható sorrendbe rendezi a diagnosztikákat. Tartsa szűken a gyökerek körét, zárja ki a fixture- és generált fákat, és nagy adattáraknál állítson be fájllimitet. A JavaScript és a Tailwind egymástól függetlenül kikapcsolható. Az élő renderelés csak a megfelelő preset kiválasztásakor fut.

A téma, a JavaScript és a Tailwind diagnosztikáit a PHPStan eredménygyorsítótára jelenti. Ha csak egy block.json fájl vagy egy szkript változik, a meleg gyorsítótár a korábbi eredményt mutathatja. Az ilyen módosítások ellenőrzésekor a gyorsítótár megkerüléséhez adja meg a --debug kapcsolót a -- után.

A kódoló ügynökökre vonatkozó projektszerződés

A csomag egy harmadik futtatható fájlt is telepít: vendor/bin/blockstudio-agents. Ez a futtatás helyéről leíró AGENTS.md fájlt ír, amire a kódoló ügynöknek szüksége van, mielőtt bármihez hozzányúl: mi készül a projektben, mely Blockstudio funkciók vannak engedélyezve, mit utasít el az elemzés, és mely parancsok alkalmazandók.

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

A kimenet egyetlen sora sem rögzített sablonból származik. Minden sor három forrás egyikéből ered:

  • A projekt saját fájljai. Egy style.css fejléccel, blokkokkal és fájlalapú oldalakkal rendelkező téma dokumentuma eltér egy olyan bővítményétől, amely csak blokkokat regisztrál. A számlálók, könyvtárak, blokk-névterek és sablonnyelvek a vizsgáló által ténylegesen megtalált értékeket mutatják, az elemzéssel azonos gyökerek és kizárások használatával.
  • blockstudio.json. Csak az engedélyezett funkciók jelennek meg, a beállított értékeikkel együtt: a blokkcímkék előtagjai és a feloldásukhoz használt névterek, Tailwind, a mellékelt UI, a szerkesztői eszközök visszaállítása, a gyorsítótár útvonala, a teljesítményprofil, a statikus előzetes renderelés és dinamikus útvonalai, a téma alapértékei, a Content Sync és a commit hook.
  • A kiválasztott phpstan.preset. A helyességi szakasz közvetlenül a presetfájlokból, rétegenként olvassa ki a szabályokat, így pontosan azokat sorolja fel, amelyeket az adott preset regisztrál. A base beállításnál a séma-, sablon-, hook- és beállítási szabályokat ismerteti. A extreme-theme beállításnál a témaszerkezeti szabályokat, a szigorú PHPStan jelzőket, a nem biztonságos PHP használatot, a kimenetkódolást, a Tailwind és a JavaScript elemet is leírja. Ha a preset új szabállyal bővül, az a generált dokumentumban is megjelenik.

A parancsok szakasz ugyanezt az elvet követi. A wp bs prerender status akkor jelenik meg, ha a statikus előzetes renderelés engedélyezett, a vendor/bin/blockstudio-githooks sync akkor, ha a githooks.commit be van állítva, a wp bs db schemas pedig akkor, ha a projektben ténylegesen van db.php.

Kapcsoló Működés
--root <path> Projektgyökér (alapértelmezés: aktuális könyvtár)
--config <path> blockstudio.json útvonala (alapértelmezés: <root>/blockstudio.json)
--output <path> Szerződés útvonala (alapértelmezés: <root>/AGENTS.md)
--stdout Kiírja a szerződést a fájlba írás helyett
--check 1 kilépési kóddal áll le, ha a lemezen lévő szerződés elavult
--force Lecserél egy olyan fájlt, amelyet a Blockstudio nem kezel

A --check a commit hookhoz hasonlóan CI-feltétellé teszi a szerződést:

Shell
vendor/bin/blockstudio-agents --check

Tulajdonjog

A generált fájl ugyanazt a jelölőt tartalmazza, mint a felügyelt commit hook, és ugyanaz a szabály érvényes rá: a Blockstudio soha nem cserél le olyan fájlt, amelyet nem ő írt. A parancs előtt már létező AGENTS.md fájlt, illetve a szerző által kézzel írt változatot elutasítja, 2 kilépési kóddal leáll, és érintetlenül hagyja, amíg meg nem adják a --force kapcsolót.

Az újragenerálás biztonságos. A fájl jegyzetrésszel zárul, és a jelölők közötti bájtok minden újrageneráláskor megmaradnak:

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

A kilépési kódok: 0, ha a szerződést megírja, aktuálisnak találja vagy kiírja; 1, ha a --check elavult szerződést talál; és 2 használati, konfigurációs vagy fájlrendszer-hiba esetén.

Mezőtípusok alakjai

A bővítmény minden Blockstudio mezőtípust egy konkrét PHP típushoz rendel:

Mezőtípus PHP típusa
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (egy) string|int
select, checkbox (több) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files (egy) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (több) list<array{id: int, url: string, ...}>
group A megnevezett csoportok aláhúzásjelekkel kezdődő előtagot használnak; a névtelen csoportok a szülő hatókörbe lapulnak be
repeater list<array{...child fields...}>
tabs A szülő hatókörbe lapul be

API vázlatok

A bővítmény a teljes Blockstudio nyilvános API-hoz tartalmaz stubokat:

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

Ezek automatikus kiegészítést és típusellenőrzést biztosítanak anélkül, hogy a Blockstudio bővítmény forráskódjára szükség lenne a gépén.

Követelmények

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (ajánlott az automatikus felismeréshez)

A csomag automatikusan telepíti a BC Math kompatibilitási szolgáltatóját. Ezért a natív ext-bcmath használata nem kötelező, még az újonnan generált témáknál sem, ha a téma- vagy extrém preset JavaScript-ellenőrzéseket engedélyez.