PHPStan
Rozšírenie blockstudio/phpstan prináša statickú analýzu do projektov Blockstudio. Pri analýze overuje šablóny blokov, súbory schém, cesty k nastaveniam a názvy hookov, takže chyby odhalí ešte pred spustením.
Inštalácia
composer require --dev blockstudio/phpstan
Typovanie šablón vo verzii 7.7 a rozšírené kontroly značiek blokov vyžadujú verziu blockstudio/phpstan 0.1.9 alebo novšiu a verziu PHPStan 2.1.47 alebo novšiu. Aktualizujte balík oddelene od zásuvného modulu:
composer require --dev blockstudio/phpstan:^0.1.9
Rozšírenie sa automaticky objaví prostredníctvom inštalátora rozšírení PHPStan. Nie je potrebná žiadna ručná konfigurácia.
Čo kontroluje
Prístup k poliam šablóny
Keď sa súbor PHP nachádza vedľa súboru block.json, rozšírenie overuje každý prístup $a['key'] podľa deklarovaných atribútov bloku.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Rozšírenie vie, že Blockstudio definuje $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview a premenné island ešte pred vložením šablóny. Priame čítania, ako napríklad $a['title'], preto neoznačí ako potenciálne nedefinované a typ premennej $a odvodí z block.json vedľa šablóny. Tvar zostane zachovaný aj po zúžení typu, takže $a['label'] ?? '', isset( $a['cta']['target'] ) a $a['cta']['title'] !== null si ponechajú deklarované typy polí; šablóna, ktorá priradí hodnotu samotnej premennej $a, si zachová priradený typ. Nepridávajte blok dokumentácie /** @var array<string, mixed> $a */: nahradí tento tvar otvoreným poľom.
Kľúče polí sa riadia pravidlami Blockstudio na zlučovanie za behu. tabs a anonymné kontajnery group bez atribútu id slúžia iba na prezentáciu, takže ich podradené polia zostávajú v nadradenom rozsahu. Názov skupiny sa pridáva pred kľúče jej podradených polí:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Opätovne použiteľné vlastné polia
Odkazy custom/* založené na súboroch sa rozbalia ešte pred kontrolou kľúčov šablóny a tvarov polí. Rozšírenie načíta zodpovedajúce field.json a uplatní rovnaké pravidlá pre idStructure, overrides, vnorené odkazy, skupiny, karty a opakovače ako 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" }
}
}
]
}
}
Výsledné kľúče šablóny sú title a hero_description. Rozpoznávajú sa v PHP, Twig, Blade, značkách blokov a odvodených tvaroch atribútov.
Chýbajúce, nejednoznačné, neplatné alebo cyklické definície založené na súboroch vyvolajú konkrétnu chybu blockstudio.customField.*. Kontroly závislých kľúčov sa pre tento blok preskočia, aby jedno nevyriešené určenie neviedlo k ďalším chybám o neznámych poliach.
Definície registrované iba za behu prostredníctvom filtra blockstudio/fields PHP nemožno odvodiť statickou analýzou. Ak má pole prispievať k staticky kontrolovaným kľúčom šablóny, použite definíciu field.json.
Prístup k šablónam Twig
Šablóny Twig sa skenujú automaticky. Anotácia nie je potrebná.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Prístup k šablónam Blade
Šablóny Blade sa skenujú rovnakým spôsobom.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Overovanie značiek blokov
Značky blokov sa overujú na miestach, kde ich číta Blockstudio: značky <bs:> a <block>, značky s predponou nakonfigurovanou v blockTags.prefixes (napríklad <acme-card>, ktorá sa rozpoznáva v poradí menných priestorov rovnako ako za behu) a značky aliasov v šablónach blokov PHP, Twig a Blade, ako aj v rozloženiach stránok. Kontrolujú sa aj zdroje stránok pod pages/ (index.php, index.html, index.twig, index.blade.php) vrátane prvkov HTML, ktoré projekt mapuje na bloky. Pribalené bloky UI sú známe, keď je zapnuté ui.enabled.
<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) -->
Atribút sa akceptuje, ak ho blok deklaruje ako pole (vrátane vlastných polí a polí, ktoré typované pole bloku sprostredkúva cez svoje idStructure), alebo ak ho Blockstudio sprostredkúva koreňovému prvku bloku: data-*, aria-*, id, style, role, title, lang, dir, hidden a tabindex. V šablónach sa prenáša každý atribút html-*; v zdrojoch stránok predpona html- označuje iba jeden zo sprostredkovaných atribútov. Nahlási sa všetko ostatné, najmä nedeklarovaný atribút class, pretože Blockstudio ho ukladá, ale nikdy nevykreslí.
Runtime registruje mapovania prvkov a aliasy značiek vo filtroch PHP, ktoré statická analýza nedokáže vyhodnotiť, preto ich analýza načíta z blockstudio.json. scanPhp kontroluje značky aj v ostatných PHP projektu, napríklad značky komponentov v moduloch, bez toho, aby tam hlásil neznáme bloky:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Prvok sa mapuje na názov bloku alebo na pravidlá skúšané v poradí: vyhrá prvé pravidlo, ktorého atribút prvok obsahuje, pričom jednoduchý názov bloku sa vždy zhoduje. Prvky, ktoré projekt nemapuje, si zachovajú svoj základný blok a nekontrolujú sa. Diagnostické správy používajú blockstudio.blockTag.unknown, blockstudio.blockTag.attribute a blockstudio.blockTag.class.
Typovanie záznamov databázy
Db::get() vracia typovanú inštanciu založenú na schéme db.php. Tvary záznamov sa odvodzujú automaticky.
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
Povinné polia nemôžu mať hodnotu null. Voliteľné polia sú type|null. Pole typu id (int) je vždy prítomné. Rovnaké typovanie funguje aj v syntaxi nástroja na tvorbu PHP-native Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Validácia ciest nastavení
Cesty Settings::get() sa kontrolujú podľa známej schémy nastavení.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Validácia názvov hákov
Overujú sa názvy filtrov Blockstudio a hookov akcií.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dynamické hooky nastavení, ako napríklad blockstudio/settings/tailwind/enabled, sú vždy povolené. Hooky nesúvisiace s blockstudio sa ignorujú.
Validácia schém
Rozšírenie overuje každý súbor schémy Blockstudio v projekte.
block.json:
- Chýba pole
name - Chýba pole
type - Chýba
idv poli hodnoty, ktoré ho vyžaduje - Neznáme typy polí
- Vlastnosti poľa, ktoré daný typ nepodporuje, napríklad
"translat"namiesto"translate"; navrhne sa najbližšia známa vlastnosť select/radio/checkboxbezoptionsalebopopulate- Duplicitné ID polí
- Pole
tabsvo vnútri opakovača, priamo alebo v skupine bezid - Neplatné deklarácie
pluginDependencies
Kontajnerové polia, ako sú group a tabs, ako aj odkazy na polia custom/*, môžu vynechať id, ak iba rozbaľujú alebo obaľujú iné polia.
Vlastnosti polí sa kontrolujú podľa vlastností, ktoré schemas/block.json deklaruje pre každý vstavaný typ poľa, a tiež podľa vlastností, ktoré prijíma každé pole. Táto kontrola nezahŕňa vlastnosti špecifické pre obaly v odkazoch custom/* ani typy polí s menným priestorom definované v projekte. Naďalej platí existujúca validácia typov polí a vlastných odkazov. Identifikátory sú blockstudio.blockJson.property a blockstudio.fieldJson.property.
Kontrolujú sa názvy vlastností, nielen ich hodnoty: minimized je platné pre opakovač, ale pri textovom poli sa nahlási. Správanie doplnku za behu sa nemení. Ak projekt zámerne pridáva vlastné metadáta k vstavaným poliam, potlačte iba tieto upozornenia bez vypnutia ostatných kontrol štruktúry:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Vstavané polia v opakovane použiteľnom field.json sa kontrolujú aj vtedy, keď má odkaz custom/* vlastné možnosti obalu. Súbory rozšírení nespadajú do rozsahu tejto diagnostiky názvov vlastností; pravidlá set špecifické pre rozšírenia zostávajú platné.
field.json (vlastné opätovne použiteľné polia):
- Chýba
name - Chýba alebo je prázdne
attributes - Neplatné objekty atribútov alebo chýbajúce pole
type - Chýba
idpri poliach hodnôt, ktoré ho vyžadujú - Neznáme typy polí
- Vlastnosti poľa, ktoré daný typ poľa neprijíma
- Pole
tabsv opakovači, priamo alebo v skupine bezid - Chýbajúce, nejednoznačné, neplatné alebo cyklické vnorené odkazy
custom/*
Rozšírenie JSON (rozšírenia blokov v extensions/):
- Chýba
name(cieľový blok) - Chýba kľúč
blockstudio - Chýba kľúč
blockstudio.extend
page.json (stránky založené na súboroch):
- Chýba
title - Chýba
slug - Neplatné hodnoty
postStatus
db.php:
- Chýba pole
fields - Neplatné typy polí
- Podporuje staršie polia aj
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Neplatné metódy HTTP
- Nesprávna hodnota
public(musí byťtrue,falsealebo'open') - Podporuje staršie polia aj návratové hodnoty objektov s atribútmi
cron.php:
- V nakonfigurovaných úlohách chýba
schedule - V nakonfigurovaných úlohách chýba
callback - Podporuje staršie polia aj návratové hodnoty objektov s atribútmi
blockstudio.json:
- Skrátené logické hodnoty, napríklad
"tailwind": true(musí sa použiť vnorený formát objektu{"enabled": true, "config": ""})
Konfigurácia
Rozšírenie štandardne vyhľadáva súbory Blockstudio v analyzovanom projekte.
Ak projekt používa bloky alebo opakovane použiteľné polia z knižnice mimo koreňového adresára projektu, pridajte cestu ku knižnici do blockstudioScanRoots. Cesta sa
preveruje na definície block.json aj field.json, takže externé značky blokov a ich vlastné polia možno overovať spoločne.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Ak chcete súbory ignorovať, použite štandardnú konfiguráciu excludePaths pre PHPStan.
Predvoľby analýzy
Automaticky objavené rozšírenie zostáva bezpečným základom z hľadiska kompatibility. Blockstudio 7.6 pridáva voliteľné vrstvy bez zmeny existujúcich projektov:
| Predvoľba | Správanie |
|---|---|
base.neon |
Analýza existujúcej schémy, šablón, hákov, nastavení a API. |
theme.neon |
Základ plus koreňové adresáre tém WordPress, hlavičky štýlov, zdroje Blockstudio, obmedzenie selektorov, predvolené hodnoty polí a limity opakovačov. |
extreme-theme.neon |
Téma plus PHPStan max, nebezpečné PHP, escapovanie výstupu, Tailwind, JavaScript a kontroly Interactivity API. |
wordpress-render.neon |
Extrémna téma plus živá renderovacia sonda WordPress dodaná volajúcim. |
Inštalácia blockstudio/phpstan aktivuje iba základné rozšírenie. Ak chcete použiť voliteľnú vrstvu, zahrňte ju do existujúcej konfigurácie PHPStan:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths riadi skener tém.
Štandardná konfigurácia excludePaths pre PHPStan nezávisle riadi analýzu PHP.
Nastavenie phpstan.excludePaths kanonického príkazu v blockstudio.json
(a jeho voľba --exclude) konfigurujú obe vrstvy. Relatívne vzory sa vyhodnocujú voči každému nakonfigurovanému koreňovému adresáru, takže položky ako vendor/** obmedzujú analýzu PHPStan aj skenovanie projektu v Blockstudio.
Vzor označujúci jeden adresár, napríklad _dist/** alebo node_modules/**,
vylúči tento adresár všade, kde sa nachádza, nielen vedľa koreňového adresára témy. Vzor obsahujúci lomku, napríklad assets/*/docs/**, zostáva ukotvený ku koreňovému adresáru. Vygenerované zdroje blokov sa nachádzajú v adresári _dist v každom bloku, preto forma s názvom jedného adresára zabráni zahrnutiu skompilovaného výstupu do analýzy.
Kanonický príkaz
Balík nainštaluje vendor/bin/blockstudio-phpstan ako spustiteľný súbor na analýzu. Ak projekt nevyberie inú predvoľbu, použije predvoľbu base. Samotná inštalácia balíka teda neaktivuje vrstvy témy ani extrémnej témy:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Predvoľby už obsahujú samotné rozšírenie. Do projektu, ktorý spúšťa kanonický príkaz, nepridávajte phpstan/extension-installer:
ak je prítomný inštalátor, extension.neon sa načíta dvakrát a PHPStan sa zastaví s hlásením „Tento súbor je zahrnutý viackrát“ ešte pred spustením analýzy.
Príkaz predvolene nastavuje pre PHPStan limit pamäte 1G, aby projekty WordPress spravované cez Composer nezdedili bežný limit CLI 128M. Ak ho chcete zmeniť, zadajte po -- explicitnú voľbu PHPStan, napríklad -- --memory-limit=512M --no-progress.
Zavedenie analýzy v existujúcom projekte
Prvé spustenie zvyčajne odhalí problémy v projekte, ktorý ešte nebol analyzovaný. Namiesto zníženia úrovne predvoľby vytvorte základný súbor PHPStan a nasmerujte phpstan.configuration na konfiguráciu projektu, ktorá ho zahŕňa. Na nový kód sa potom vzťahuje plná predvoľba a zaznamenané nálezy neprekážajú:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Pre predvoľby base a theme ponechajte riadok level. Kanonický príkaz pre ne nastaví úroveň max iba vtedy, keď nie je zahrnutá konfigurácia projektu. Bez úrovne PHPStan sa zastaví s hlásením „Neboli zistené žiadne pravidlá“. Predvoľba extreme-theme nastavuje úroveň max sama.
Relatívne cesty sa vyhodnocujú od blockstudio.json. Kanonický príkaz aj spravovaný hák pre potvrdenie zmien tento súbor prevezmú, takže hák kontroluje nové nálezy bez toho, aby bolo najprv potrebné vyriešiť nevybavené nálezy.
Predvolené hodnoty príkazov pre celý projekt ponechajte v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Relatívne koreňové adresáre sa vyhodnocujú od súboru, v ktorom sú deklarované. Explicitné hodnoty CLI nahrádzajú zodpovedajúce hodnoty JSON. Ak chcete použiť iný zdroj konfigurácie, zadajte --blockstudio-json path/to/project.json. Chybný JSON, nepodporované kľúče phpstan, neplatné hodnoty a chýbajúci explicitný zdroj vedú deterministicky k ukončeniu s návratovým kódom 2.
Vyberte inú predvoľbu, zahrňte konfiguráciu projektu, pridajte opakovateľné koreňové adresáre a vylúčenia alebo požiadajte PHPStan o JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Obalový skript skladá konfiguráciu v dočasnom systémovom adresári a pri ukončení ju odstráni. Do analyzovaného projektu nikdy nezapisuje vygenerovanú konfiguráciu, základné súbory, háky ani vyrovnávaciu pamäť. Volajúci môžu napriek tomu explicitne nastaviť bežnú vyrovnávaciu pamäť pre PHPStan.
Zmluva o návratových kódoch:
0pri úspešnej analýze1, keď PHPStan nahlási diagnostické správy2pri nesprávnom použití, chybe konfigurácie alebo vykonávania procesu
Spravovaná kontrola pri commite
Ak chcete z analýzy extrémnej témy urobiť podmienku potvrdenia zmien v repozitári, povoľte hák spravovaný cez Blockstudio v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Po nainštalovaní závislostí alebo zmene nastavenia ho synchronizujte:
vendor/bin/blockstudio-githooks sync
Príkaz zapisuje vygenerovaný hák pred potvrdením zmien aj záznam o jeho správe do spoločného adresára Git, nastaví core.hooksPath na adresár spravovaných hákov a bezpečne nadviaže na predtým nakonfigurovaný hák pred potvrdením zmien. Opakovaná synchronizácia aktualizuje iba vygenerovaný súbor, takže aktualizácie balíka sú idempotentné.
Nastavte commit na false, odstráňte ho alebo odstráňte blockstudio.json a potom spustite sync, aby sa obnovila zaznamenaná cesta k háku a odstránili iba súbory spravované cez Blockstudio. Môžete tiež spustiť:
vendor/bin/blockstudio-githooks remove
Súbory spravované používateľom sa nikdy neprepisujú ani neodstraňujú. Ak niekto po povolení Blockstudio zmení core.hooksPath, pri odstránení sa toto novšie nastavenie zachová. Vygenerovaný hák podporuje prepojené pracovné kópie Git aj cesty obsahujúce medzery, pretože v čase potvrdenia zmien zisťuje aktívny repozitár a koreňový adresár projektu. Kanonický príkaz spúšťa z tohto koreňového adresára, takže ten istý objekt phpstan riadi interaktívne spustenia aj potvrdenia zmien bez duplicitne vygenerovaných argumentov.
Hák spúšťa iba vendor/bin/blockstudio-phpstan. Blockstudio nespúšťa formátovač a hák nikdy neprepisuje súbory projektu. Chýbajúce závislosti a zlyhania analýzy zablokujú potvrdenie zmien a zobrazia pokyny na riešenie problému.
Živé vykresľovanie WordPress
Živá vrstva je zámerne explicitná. Volajúci spravuje prostredie WordPress a poskytuje pole argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Príkaz sa spúšťa bez shellu a musí vypísať jeden objekt JSON:
{"ok":true}
Sonda môže nahlásiť konkrétnu chybu:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Nenulové návratové kódy, časové limity, chybný JSON a ok: false vedú k blockstudio.wordpress.render.
blockstudio.javascript.domContract nahlasuje selektor atribútu [data-*], ktorý skript odovzdá do querySelector(), querySelectorAll(), closest() alebo matches(), ak žiadna analyzovaná značka tento atribút nemá. Značky zahŕňajú každý súbor PHP, Twig, Blade a HTML, ako aj každý komponent React .tsx a .jsx v analyzovaných koreňových priečinkoch, okrem vylúčených ciest. Komponenty sa parsujú: počítajú sa názvy atribútov JSX aj reťazcové kľúče objektových literálov, takže objekt atribútov rozbalený do prvku vyhovuje selektoru, zatiaľ čo názvy tried a iné hodnoty atribútov nie.
Kontroly API Interactivity čítajú tie isté komponenty React. Menný priestor data-wp-interactive na prvku JSX sa považuje za odkaz na šablónu pre blockstudio.interactivity.orphan a direktívy data-wp-* v ňom sa vyhodnocujú podľa najbližšieho nadradeného menného priestoru alebo podľa predpony namespace:: v hodnote. Direktívy so statickou reťazcovou hodnotou, zapísanou ako atribút JSX alebo ako reťazcový kľúč objektu atribútov, musia odkazovať na existujúce obslužné funkcie a cesty úložiska (blockstudio.interactivity.handler, blockstudio.interactivity.binding) a kód úložiska nesmie meniť atribúty ani triedy, na ktoré sú naviazané (blockstudio.interactivity.derivedState). React escapuje hodnoty atribútov, preto sa data-wp-context v komponente nehlási; dynamické hodnoty sa nekontrolujú. Menné priestory pod bsui/ patria k pribaleným blokom UI, ktorých úložiská sa dodávajú s Blockstudio mimo analyzovaných koreňových priečinkov, takže nikdy nie sú osirelé.
Identifikátory diagnostických správ
Nová diagnostika predvolieb si zachováva stabilné identifikátory blockstudio.*:
- Štruktúra témy:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Zdroje a polia:
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 - Interaktivita:
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
Výkon
Skener prijíma bežné zmaterializované adresáre, odstraňuje duplicitné koreňové adresáre, preskakuje adresáre závislostí, zostavení a vyrovnávacej pamäte, ukladá načítané súbory do pamäte a triedi diagnostické správy deterministicky. Udržujte koreňové adresáre úzke, vylúčte testovacie a generované adresáre a pre veľké repozitáre nastavte limit počtu súborov. JavaScript a Tailwind možno vypnúť nezávisle. Živé vykresľovanie sa spustí iba po výbere príslušnej predvoľby.
Diagnostické správy pre témy, JavaScript a Tailwind sa oznamujú cez vyrovnávaciu pamäť výsledkov PHPStan. Ak zmeníte iba block.json alebo skript, teplá vyrovnávacia pamäť môže vrátiť predchádzajúci výsledok. Ak chcete pri overovaní takýchto zmien obísť vyrovnávaciu pamäť, zadajte po -- voľbu --debug.
Zmluva projektu pre kódovacích agentov
Balík nainštaluje tretí spustiteľný súbor vendor/bin/blockstudio-agents. Ten zapíše súbor AGENTS.md s opisom projektu, v ktorom sa spúšťa. Kódovací agent ho potrebuje skôr, než sa čohokoľvek dotkne: čo projekt vytvára, ktoré funkcie Blockstudio sú povolené, ktoré problémy analýza zamietne a ktoré príkazy sa používajú.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Žiadny riadok výstupu nie je pevne danou šablónou. Každý vychádza z jedného z troch zdrojov:
- Vlastné súbory projektu. Téma s hlavičkou
style.css, blokmi a stránkami uloženými v súboroch vytvorí iný dokument než doplnok, ktorý registruje bloky a nič iné. Počty, adresáre, menné priestory blokov a jazyky šablón zodpovedajú skutočným zisteniam skenera pri použití rovnakých koreňových adresárov a vylúčení ako pri analýze. blockstudio.json. Opisujú sa iba povolené funkcie vrátane nakonfigurovaných hodnôt: predpony značiek blokov a menné priestory, cez ktoré sa rozpoznávajú, Tailwind, pribalený UI, reset zdrojov editora, cesta k vyrovnávacej pamäti, profil výkonu, statické predvykresľovanie a jeho dynamické cesty, predvolené hodnoty témy, Content Sync a hák pri potvrdení zmien.- Vybraná predvoľba
phpstan.preset. Sekcia správnosti sa číta priamo zo súborov predvolieb po jednotlivých vrstvách, takže uvádza presne tie pravidlá, ktoré predvoľba registruje. Pribaseopisuje pravidlá pre schému, šablóny, háky a nastavenia. Priextreme-themeopisuje aj pravidlá štruktúry témy, prísne príznaky PHPStan, nebezpečné PHP, escapovanie výstupu, Tailwind a JavaScript. Ak predvoľba získa nové pravidlo, zmení sa aj vygenerovaný dokument.
Sekcia príkazov funguje rovnako. wp bs prerender status sa zobrazí, keď je povolené statické predvykresľovanie, vendor/bin/blockstudio-githooks sync, keď je nastavené githooks.commit, a wp bs db schemas, keď projekt skutočne obsahuje db.php.
| Možnosť | Správanie |
|---|---|
--root <path> |
Koreňový adresár projektu (predvolené: aktuálny adresár) |
--config <path> |
Cesta k blockstudio.json (predvolené: <root>/blockstudio.json) |
--output <path> |
Cesta k zmluve (predvolené: <root>/AGENTS.md) |
--stdout |
Vypíše zmluvu namiesto jej zápisu |
--check |
Ukončí sa s kódom 1, ak zmluva na disku nie je aktuálna |
--force |
Nahradí súbor, ktorý Blockstudio nespravuje |
--check umožňuje použiť zmluvu ako podmienku CI, podobne ako hák pri potvrdení zmien podmieňuje analýzu:
vendor/bin/blockstudio-agents --check
Správa súborov
Vygenerovaný súbor obsahuje rovnaký typ značky ako spravovaný hák pri potvrdení zmien a platí preň rovnaké pravidlo: Blockstudio nikdy nenahrádza súbor, ktorý nevytvoril.
Ak súbor AGENTS.md existoval ešte pred zavedením príkazu alebo ho autor vytvoril ručne, operácia bude odmietnutá s návratovým kódom 2 a súbor zostane nedotknutý, kým sa nezadá --force.
Opätovné generovanie je bezpečné. Súbor sa končí oblasťou poznámok a bajty medzi jej značkami zostávajú zachované pri každom generovaní:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Návratové kódy: 0 pri zápise, aktuálnosti alebo výpise zmluvy, 1, keď --check zistí zastaranú zmluvu, a 2 pri chybách použitia, konfigurácie alebo súborového systému.
Tvary typov polí
Rozšírenie mapuje každý typ poľa Blockstudio na konkrétny typ PHP:
| Typ poľa | Typ PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (jedno) |
string|int |
select, checkbox (viacero) |
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 (jedno) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (viacero) |
list<array{id: int, url: string, ...}> |
group |
Pomenované skupiny používajú predpony s podčiarkovníkom; anonymné skupiny sa zlúčia do nadradeného rozsahu |
repeater |
list<array{...child fields...}> |
tabs |
Zlúčené do nadradeného rozsahu |
Zástupné definície API
Rozšírenie obsahuje zástupné definície pre celé verejné rozhranie Blockstudio API:
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()
Poskytujú automatické dopĺňanie a kontrolu typov bez potreby mať v počítači zdrojový kód doplnku Blockstudio.
Požiadavky
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(odporúčané na automatické vyhľadávanie)
Balík automaticky nainštaluje poskytovateľa kompatibility s BC Math. Natívne ext-bcmath je preto voliteľné, a to aj pri novovygenerovaných témach, ktoré aktivujú kontroly JavaScript cez predvoľbu témy alebo extrémnej témy.