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
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:
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
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:
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:
{
"name": "mytheme/hero",
"attributes": [
{ "id": "heading", "type": "text" },
{ "id": "description", "type": "textarea" }
]
}
{
"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.
<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.
<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.
<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:
{
"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ő.
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$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.
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.
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ó
namemező - Hiányzó
typemező - Hiányzó
idolyan é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/checkboxoptionsvagypopulatenélkül- Duplikált mezőazonosítók
tabsmező egy ismétlőben, közvetlenül vagy egy csoporton belül,idnélkül- Érvénytelen
pluginDependenciesdeklará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:
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ó
idaz azt igénylő értékmezőkön - Ismeretlen mezőtípusok
- Olyan mezőtulajdonságok, amelyeket a mezőtípus nem fogad el
tabsmező ismétlő mezőn belül, közvetlenül vagy egy csoportban,idné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ó
blockstudiokulcs - Hiányzó
blockstudio.extendkulcs
page.json (fájlalapú oldalak):
- Hiányzik:
title - Hiányzik:
slug - Érvénytelen
postStatusértékek
db.php:
- Hiányzik a
fieldstömb - Érvénytelen mezőtípusok
- A régi tömböket és a
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Fieldformátumot is támogatja
rpc.php:
- Érvénytelen HTTP metódusok
- Hibás
publicérték (csaktrue,falsevagy'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
schedulea konfigurált feladatoknál - Hiányzik a
callbacka 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.
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:
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:
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:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"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:
{
"$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.
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 sikeres1, ha a PHPStan diagnosztikai üzeneteket jelez2é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:
{
"$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:
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:
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:
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:
{"ok":true}
A próba célzott hibát is jelezhet:
{
"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.
vendor/bin/blockstudio-agents
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.cssfejlé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. Abasebeállításnál a séma-, sablon-, hook- és beállítási szabályokat ismerteti. Aextreme-themebeá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:
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:
## 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.