PHPStan
Rozšíření blockstudio/phpstan přidává statickou analýzu do projektů Blockstudio. Během analýzy ověřuje šablony bloků, soubory schémat, cesty k nastavením a názvy hooků, takže odhalí chyby dřív, než se projeví za běhu.
Instalace
composer require --dev blockstudio/phpstan
Typování šablon ve verzi 7.7 a rozšířené kontroly značek bloků vyžadují blockstudio/phpstan 0.1.9 nebo novější a PHPStan 2.1.47 nebo novější. Aktualizujte balíček zvlášť od pluginu:
composer require --dev blockstudio/phpstan:^0.1.9
Rozšíření se automaticky najde prostřednictvím instalátoru rozšíření PHPStan. Ruční konfigurace není potřeba.
Co kontroluje
Přístup k polím šablony
Pokud se soubor PHP nachází vedle souboru block.json, rozšíření ověří každý přístup $a['key'] podle deklarovaných atributů bloku.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Rozšíření ví, že Blockstudio definuje $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview a proměnné islandů ještě před vložením šablony. Přímé čtení, například $a['title'], proto nehlásí jako možná nedefinované a typ $a odvodí ze souboru block.json vedle šablony. Tvar se zachová i při zužování typu, takže $a['label'] ?? '', isset( $a['cta']['target'] ) a $a['cta']['title'] !== null si ponechají deklarované typy polí; proměnná $a si zachová typ, který jí šablona přiřadila. Nepřidávejte dokumentační blok /** @var array<string, mixed> $a */: nahradil by tento tvar otevřeným polem.
Klíče polí se řídí pravidly zploštění za běhu v Blockstudio. Kontejnery tabs a anonymní group bez id slouží pouze k prezentaci, takže jejich podřízená pole zůstávají v rozsahu nadřazeného prvku. Skupina s názvem přidá ID skupiny jako prefix klíčů svých podřízených polí:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Opakovaně použitelná vlastní pole
Odkazy custom/* na soubory se rozbalí před kontrolou klíčů šablony a tvarů polí. Rozšíření načte odpovídající field.json a uplatní stejná pravidla pro idStructure, overrides, vnořené odkazy, skupiny, karty a opakovače jako 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é klíče šablony jsou title a hero_description. Jsou rozpoznány v PHP, Twig, Blade, značkách bloků i odvozených tvarech atributů.
Pokud definice založená na souboru chybí, je nejednoznačná, neplatná nebo cyklická, zobrazí se konkrétní chyba blockstudio.customField.*. Kontroly závislých klíčů se pro daný blok přeskočí, aby jediná nevyřešená definice nevyvolala další vlnu falešných chyb o neznámých polích.
Definice registrované pouze za běhu prostřednictvím filtru blockstudio/fields PHP nelze při statické analýze odvodit. Pokud má pole přispívat ke staticky kontrolovaným klíčům šablony, použijte definici field.json.
Přístup k šablonám Twig
Šablony Twig se prohledávají automaticky. Anotace není potřeba.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Přístup k šablonám Blade
Šablony Blade se prohledávají stejným způsobem.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Ověřování značek bloků
Značky bloků se ověřují na místech, kde je Blockstudio načítá: u značek <bs:> a <block>, značek s prefixy nastavenými v blockTags.prefixes (například <acme-card>, které se rozpoznávají v pořadí jmenných prostorů stejně jako za běhu) a aliasů, v šablonách bloků PHP, Twig a Blade i v rozvrženích stránek. Kontrolují se také zdroje stránek pod pages/ (index.php, index.html, index.twig, index.blade.php), včetně elementů HTML, které projekt mapuje na bloky. Dodávané bloky UI jsou rozpoznány, pokud je zapnuto 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) -->
Atribut je přijat, pokud jej blok deklaruje jako pole (včetně vlastních polí a polí, která pole typu blok předává v rámci idStructure) nebo pokud jej do kořenového elementu bloku předává Blockstudio: data-*, aria-*, id, style, role, title, lang, dir, hidden a tabindex. V šablonách se předává každý atribut html-*; ve zdrojích stránek prefix html- označuje pouze jeden z předávaných atributů. Vše ostatní se hlásí, především nedeklarované class, protože Blockstudio tento atribut ukládá, ale nikdy jej nevykreslí.
Za běhu registruje mapování elementů a aliasy značek pomocí filtrů PHP, které statická analýza nedokáže vyhodnotit, a proto je načítá z blockstudio.json. scanPhp kontroluje také značky v dalších souborech projektu PHP, například značky komponent v modulech, aniž by tam hlásilo neznámé 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
}
}
}
Element se mapuje na název bloku nebo na pravidla zkoušená v daném pořadí: použije se první pravidlo, jehož atribut element obsahuje; prostý název bloku odpovídá vždy. Elementy, které projekt nemapuje, si ponechají svůj základní blok a nekontrolují se. Diagnostika používá blockstudio.blockTag.unknown, blockstudio.blockTag.attribute a blockstudio.blockTag.class.
Typování záznamů databáze
Db::get() vrací typovanou instanci podle schématu db.php. Tvary záznamů se odvozují 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á pole nemohou mít hodnotu null. Volitelná pole jsou type|null. Pole typu id (int) je vždy přítomné. Stejné typování funguje i se syntaxí nástroje PHP Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Ověřování cest k nastavením
Cesty Settings::get() se ověřují podle známého schématu nastavení.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Ověřování názvů hooků
Názvy hooků filtrů a akcí Blockstudio se ověřují.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dynamické hooky nastavení, jako je blockstudio/settings/tailwind/enabled, jsou vždy povolené. Hooky nesouvisející s blockstudio se ignorují.
Ověřování schémat
Rozšíření ověřuje všechny soubory schémat Blockstudio v projektu.
block.json:
- Chybí pole
name - Chybí pole
type - U hodnotových polí chybí
id, které je pro ně povinné - Neznámé typy polí
- Vlastnosti polí, které daný typ nepřijímá, například
"translat"místo"translate", s návrhem nejbližší známé vlastnosti select/radio/checkboxbezoptionsnebopopulate- Duplicitní ID polí
- Pole
tabsuvnitř opakovače, přímo nebo ve skupině bezid - Neplatné deklarace
pluginDependencies
Kontejnerová pole, jako jsou group a tabs, i odkazy na pole custom/* mohou vynechat id, pokud pouze rozbalují nebo obalují jiná pole.
Vlastnosti polí se kontrolují podle vlastností schemas/block.json, které deklaruje pro každý vestavěný typ pole, a také podle vlastností přijímaných všemi poli. Vlastnosti specifické pro obal u odkazů custom/* a typy polí s názvy v prostoru jmen definované projektem tato kontrola nezahrnuje. Stávající ověřování typů polí a vlastních odkazů zůstává v platnosti. Identifikátory jsou blockstudio.blockJson.property a blockstudio.fieldJson.property.
Kontrolují se názvy vlastností, nejen jejich hodnoty: minimized je platné u opakovače, ale u textového pole se nahlásí. Chování pluginu za běhu se nemění. Pokud projekt záměrně připojuje k vestavěným polím vlastní metadata, potlačte pouze tato upozornění, aniž byste vypnuli ostatní kontroly struktury:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Vestavěná pole uvnitř opakovaně použitelného field.json se stále kontrolují, i když má odkaz custom/* vlastní možnosti obalu. Soubory rozšíření jsou mimo rozsah této diagnostiky názvů vlastností; pravidla set specifická pro rozšíření zůstávají platná.
field.json (opakovaně použitelná vlastní pole):
- Chybí
name - Chybí nebo je prázdné
attributes - Neplatné objekty atributů nebo chybějící
typepole - Chybí
idu hodnotových polí, která jej vyžadují - Neznámé typy polí
- Vlastnosti polí, které daný typ pole nepřijímá
- Pole
tabsuvnitř opakovače, přímo nebo ve skupině bezid - Chybějící, nejednoznačné, neplatné nebo cyklické vnořené odkazy
custom/*
Rozšíření JSON (rozšíření bloků v extensions/):
- Chybějící
name(cílový blok) - Chybějící klíč
blockstudio - Chybějící klíč
blockstudio.extend
page.json (stránky založené na souborech):
- Chybí
title - Chybí
slug - Neplatné hodnoty
postStatus
db.php:
- Chybí pole
fields - Neplatné typy polí
- Podporuje starší pole i
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Neplatné metody HTTP
- Nesprávná hodnota
public(musí býttrue,falsenebo'open') - Podporuje starší pole i vrácené objekty s atributy
cron.php:
- U nakonfigurovaných úloh chybí
schedule - U nakonfigurovaných úloh chybí
callback - Podporuje starší pole i vrácené objekty s atributy
blockstudio.json:
- Zkrácené booleovské zápisy jako
"tailwind": true(je nutné použít vnořený formát objektu{"enabled": true, "config": ""})
Konfigurace
Rozšíření ve výchozím nastavení vyhledává soubory Blockstudio v analyzovaném projektu.
Pokud projekt používá bloky nebo opakovaně použitelné položky z knihovny mimo
kořenový adresář projektu, přidejte cestu ke knihovně do blockstudioScanRoots. Cesta se
prohledává kvůli definicím block.json i field.json, takže lze společně ověřovat externí značky
bloků i jejich vlastní pole.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Chcete-li některé soubory ignorovat, použijte standardní konfiguraci excludePaths nástroje PHPStan.
Předvolby analýzy
Automaticky nalezené rozšíření zůstává základem zajišťujícím kompatibilitu. Blockstudio Verze 7.6 přidává volitelné vrstvy, aniž by měnila stávající projekty:
| Předvolba | Chování |
|---|---|
base.neon |
Stávající analýza schémat, šablon, hooků, nastavení a API. |
theme.neon |
Základní předvolba doplněná o kořenové adresáře WordPress šablony, hlavičky stylů, prostředky Blockstudio, omezení rozsahu selektorů, výchozí hodnoty polí a limity opakovačů. |
extreme-theme.neon |
Předvolba Theme doplněná o PHPStan max, nebezpečné PHP, escapování výstupu, Tailwind, JavaScript a kontroly API Interactivity. |
wordpress-render.neon |
Extrémní předvolba Theme doplněná o živou testovací sondu WordPress zadanou volajícím. |
Instalací blockstudio/phpstan se aktivuje pouze základní rozšíření. Chcete-li přidat volitelnou vrstvu, zahrňte ji do stávající konfigurace PHPStan:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths ovládá skener šablon.
Standardní excludePaths nástroje PHPStan samostatně ovládá analýzu PHP.
Nastavení phpstan.excludePaths kanonického příkazu v blockstudio.json
(a jeho volba --exclude) konfiguruje obě vrstvy. Relativní vzory se vyhodnocují
vůči každému nakonfigurovanému kořeni, takže položky jako vendor/** omezují analýzu PHPStan
i skenování projektu nástrojem Blockstudio.
Vzorek označující jeden adresář, například _dist/** nebo node_modules/**,
vyloučí tento adresář bez ohledu na jeho umístění, nejen vedle kořenového adresáře šablony. Vzorek
obsahující lomítko, například assets/*/docs/**, zůstává navázaný na kořen. Vygenerované prostředky bloku jsou
uložené v adresáři _dist uvnitř každého bloku, takže forma s názvem jednoho adresáře zabrání zahrnutí zkompilovaného výstupu do analýzy.
Kanonický příkaz
Balíček instaluje vendor/bin/blockstudio-phpstan jako spustitelný soubor pro analýzu.
Pokud projekt nezvolí jinou, použije se předvolba base. Samotná instalace balíčku tedy neaktivuje vrstvy Theme ani Extreme Theme:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Předvolby obsahují samotné rozšíření. Do projektu, který spouští kanonický příkaz,
nepřidávejte phpstan/extension-installer:
pokud je nainstalováno, načte se extension.neon dvakrát a PHPStan se zastaví
s hlášením „Tento soubor je zahrnut vícekrát“ ještě před zahájením analýzy.
Příkaz ve výchozím nastavení nastaví PHPStan na limit paměti 1G, aby projekty WordPress spravované pomocí Composer nepodléhaly obvyklému limitu CLI 128M. Chcete-li toto nastavení přepsat, zadejte za -- explicitní volbu PHPStan, například -- --memory-limit=512M --no-progress.
Zavedení analýzy do stávajícího projektu
Projekt, který dosud nebyl analyzován, při prvním spuštění obvykle nahlásí problémy. Místo snížení úrovně předvolby vygenerujte základní soubor PHPStan a nasměrujte phpstan.configuration na konfiguraci projektu, která jej zahrnuje. Nový kód pak musí splňovat požadavky celé předvolby, zatímco zaznamenané problémy nebudou překážet:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Pro předvolby base a theme ponechte řádek level. Kanonický příkaz
nastaví pro ně úroveň max pouze tehdy, když není zahrnuta žádná konfigurace projektu; bez úrovně PHPStan se zastaví s hlášením „Nebyla nalezena žádná pravidla“. Předvolba extreme-theme nastavuje úroveň max sama.
Relativní cesty se vyhodnocují od blockstudio.json. Kanonický příkaz i spravovaný hook pro potvrzování změn soubor najdou, takže hook kontroluje nové nálezy, aniž by bylo nutné nejprve vyřešit všechny dosavadní problémy.
Výchozí hodnoty příkazů pro celý projekt ponechte v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Relativní kořenové cesty se vyhodnocují od souboru, který je deklaruje. Explicitní hodnoty CLI nahrazují odpovídající hodnoty JSON. Alternativní zdroj konfigurace zadáte pomocí --blockstudio-json path/to/project.json. Chybně formátované JSON, nepodporované klíče phpstan, neplatné hodnoty a chybějící explicitní zdroj způsobí předvídatelné ukončení s návratovým kódem 2.
Vyberte jinou předvolbu, zahrňte konfiguraci projektu, přidejte opakovatelně zadávané kořenové adresáře a výjimky nebo požádejte 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 skládá konfiguraci v dočasném systémovém adresáři a při ukončení ji smaže. Do analyzovaného projektu nikdy nezapisuje vygenerovanou konfiguraci, základní soubory, hooky ani mezipaměti. Volající přesto mohou výslovně nakonfigurovat obvyklou mezipaměť nástroje PHPStan.
Návratové hodnoty jsou následující:
0při úspěšné analýze1pokud PHPStan nahlásí diagnostická hlášení2při nesprávném použití, chybě konfigurace nebo spuštění procesu
Spravovaný commit hook
Chcete-li z analýzy Extreme Theme udělat kontrolní bránu při potvrzování změn do repozitáře, aktivujte hook spravovaný nástrojem Blockstudio v blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Po instalaci závislostí nebo změně nastavení jej synchronizujte:
vendor/bin/blockstudio-githooks sync
Příkaz zapíše vygenerovaný hook pro potvrzování změn a záznam o jeho vlastnictví do společného adresáře nástroje Git, nastaví core.hooksPath na adresář spravovaného hooku a bezpečně naváže na dříve nakonfigurovaný hook pro potvrzování změn. Opakovaná synchronizace obnovuje pouze vygenerovaný soubor, takže aktualizace balíčku lze provádět opakovaně bez vedlejších účinků.
Nastavte commit na false, odeberte jej nebo odeberte blockstudio.json a potom spusťte sync, aby se obnovila zaznamenaná cesta k hooku a odstranily pouze soubory vlastněné Blockstudio. Můžete také spustit:
vendor/bin/blockstudio-githooks remove
Soubory vlastněné uživatelem se nikdy nepřepisují ani nemažou. Pokud někdo změní core.hooksPath po aktivaci Blockstudio, při odebrání zůstane toto novější nastavení zachováno. Vygenerovaný hook podporuje propojené pracovní kopie Git i cesty obsahující mezery, protože při potvrzování změn zjišťuje aktivní repozitář a kořen projektu. Kanonický příkaz spouští z tohoto kořene, takže stejný objekt phpstan řídí interaktivní spuštění i potvrzování změn bez duplicitních vygenerovaných argumentů.
Hook spouští pouze vendor/bin/blockstudio-phpstan. Blockstudio nespouští formátovač a hook nikdy nepřepisuje soubory projektu. Chybějící závislosti a chyby analýzy zablokují potvrzení změn a zobrazí konkrétní pokyny k nápravě.
Živé vykreslování WordPress
Živá vrstva je záměrně explicitní. Volající odpovídá za prostředí WordPress a předává 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 .
Příkaz se spouští bez shellu a musí vypsat jeden objekt JSON:
{"ok":true}
Testovací sonda může nahlásit konkrétní chybu:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Návratové kódy jiné než nula, překročení časového limitu, chybně formátované JSON a ok: false vedou k výsledku blockstudio.wordpress.render.
blockstudio.javascript.domContract hlásí selektor atributu [data-*], který skript předává do querySelector(), querySelectorAll(), closest() nebo matches(), pokud tento atribut neobsahuje žádné analyzované značení. Značení zahrnuje všechny soubory PHP, Twig, Blade a HTML a také všechny komponenty React .tsx a .jsx v analyzovaných kořenech po odečtení vyloučených cest. Komponenty se parsují: počítají se názvy atributů JSX i řetězcové klíče objektových literálů, takže objekt atributů rozprostřený na element splňuje selektor, zatímco názvy tříd a jiné hodnoty atributů nikoli.
Kontroly Interactivity API čtou stejné komponenty React. Pro blockstudio.interactivity.orphan se jmenný prostor data-wp-interactive na elementu JSX počítá jako odkaz na šablonu a direktivy data-wp-* uvnitř něj se vyhodnocují podle nejbližšího nadřazeného jmenného prostoru nebo podle předpony namespace:: v hodnotě. Direktivy se statickou řetězcovou hodnotou, zapsané jako atribut JSX nebo jako řetězcový klíč objektu atributů, musí odkazovat na existující obslužné funkce a cesty úložiště (blockstudio.interactivity.handler, blockstudio.interactivity.binding) a kód úložiště nesmí měnit atributy a třídy, na které jsou navázané (blockstudio.interactivity.derivedState). React escapuje hodnoty atributů, takže data-wp-context v komponentě se nehlásí; dynamické hodnoty se nekontrolují. Jmenné prostory pod bsui/ patří k přibaleným blokům UI, jejichž úložiště jsou dodávána s Blockstudio mimo analyzované kořeny, takže nikdy nejsou osiřelá.
Identifikátory diagnostických hlášení
Nová diagnostická hlášení předvoleb zachovávají stabilní ID blockstudio.*:
- Struktura šablony:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Prostředky a pole:
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 - Interactivity:
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 přijímá běžné materializované adresáře, odstraňuje duplicitní kořenové cesty, přeskakuje adresáře závislostí, sestavení a mezipamětí, ukládá obsah souborů do mezipaměti v paměti a diagnostická hlášení řadí předvídatelně. Zvolte úzké kořenové cesty, vynechte adresáře s testovacími a generovanými soubory a u velkých repozitářů nastavte limit počtu souborů. JavaScript a Tailwind lze vypnout nezávisle. Živé vykreslování se spustí pouze při výběru příslušné předvolby.
Diagnostická hlášení pro Theme, JavaScript a Tailwind se poskytují prostřednictvím mezipaměti výsledků nástroje PHPStan. Pokud změníte pouze block.json nebo skript, může zahřátá mezipaměť vrátit předchozí výsledek. Chcete-li tyto změny ověřit bez použití mezipaměti, zadejte za -- volbu --debug.
Smlouva o projektu pro programovací agenty
Balíček instaluje třetí spustitelný soubor, vendor/bin/blockstudio-agents. Ten
zapíše AGENTS.md s popisem projektu, ve kterém je spuštěn. Právě to programovací agent potřebuje, než začne cokoli měnit: co projekt vytváří, které funkce Blockstudio jsou zapnuté, co analýza odmítne a které příkazy se na projekt vztahují.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Žádná část výstupu není pevnou šablonou. Každý řádek vychází z jednoho ze tří zdrojů:
- Vlastní soubory projektu. Šablona s hlavičkou
style.css, bloky a stránkami uloženými v souborech vytvoří jiný dokument než plugin, který registruje pouze bloky. Počty, adresáře, jmenné prostory bloků a jazyky šablon odpovídají skutečným výsledkům skenování, které používá stejné kořenové cesty a výjimky jako analýza. blockstudio.json. Popisují se pouze zapnuté funkce a jejich nakonfigurované hodnoty: předpony značek bloků a jmenné prostory, přes které se vyhodnocují, Tailwind, přibalené UI, reset prostředků editoru, cesta k mezipaměti, profil výkonu, statické předběžné vykreslování a jeho dynamické cesty, výchozí hodnoty šablony, synchronizace obsahu a hook pro potvrzování změn.- Vybraná
phpstan.preset. Část o správnosti se čte přímo ze souborů předvoleb, vrstvu po vrstvě, a uvádí přesně ta pravidla, která předvolba registruje. Předvolbabasepopisuje pravidla pro schémata, šablony, hooky a nastavení. Předvolbaextreme-themenavíc popisuje pravidla struktury šablony, striktní příznaky PHPStan, nebezpečné PHP, escapování výstupu, Tailwind a JavaScript. Pokud předvolba získá nové pravidlo, změní se podle toho i generovaný dokument.
Sekce s příkazy se řídí stejným principem. wp bs prerender status se zobrazí, je-li zapnuté statické předběžné vykreslování, vendor/bin/blockstudio-githooks sync, pokud je nastaveno githooks.commit, a wp bs db schemas, pokud projekt skutečně obsahuje db.php.
| Volba | Chování |
|---|---|
--root <path> |
Kořen projektu (výchozí: aktuální adresář) |
--config <path> |
Cesta blockstudio.json (výchozí: <root>/blockstudio.json) |
--output <path> |
Cesta ke smlouvě (výchozí: <root>/AGENTS.md) |
--stdout |
Vypíše smlouvu místo jejího zápisu |
--check |
Ukončí se s kódem 1, pokud smlouva na disku není aktuální |
--force |
Nahradí soubor, který nástroj Blockstudio nevlastní |
--check umožňuje použít smlouvu jako kontrolní bránu v CI, stejně jako hook pro potvrzování změn slouží ke kontrole analýzy:
vendor/bin/blockstudio-agents --check
Vlastnictví
Vygenerovaný soubor obsahuje stejný typ značky jako spravovaný hook pro potvrzování změn a platí stejné pravidlo: Blockstudio nikdy nenahrazuje soubor, který samo nezapsalo.
Pokud soubor AGENTS.md existoval již před příkazem nebo jej autor vytvořil ručně, příkaz jeho přepsání odmítne s návratovým kódem 2 a ponechá jej beze změny, dokud nebude zadáno --force.
Bezpečně jej lze generovat opakovaně. Soubor končí oblastí pro poznámky a bajty mezi jejími značkami zůstanou zachovány při každém opětovném generování:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Návratové kódy jsou 0 při zápisu, aktuálnosti nebo výpisu smlouvy, 1, pokud --check zjistí zastaralou smlouvu, a 2 při chybách použití, konfigurace nebo souborového systému.
Tvary typů polí
Rozšíření mapuje každý typ pole Blockstudio na konkrétní typ PHP:
| Typ pole | 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 (více) |
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 (více) |
list<array{id: int, url: string, ...}> |
group |
Pojmenované skupiny používají předpony podtržítka; anonymní skupiny se sloučí do nadřazeného rozsahu |
repeater |
list<array{...child fields...}> |
tabs |
Sloučeno do nadřazeného rozsahu |
Deklarace typů API
Rozšíření obsahuje deklarace typů pro celé veřejné 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í našeptávání a kontrolu typů bez nutnosti mít ve svém počítači zdrojový kód pluginu Blockstudio.
Požadavky
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(doporučeno pro automatické vyhledávání)
Balíček automaticky instaluje poskytovatele kompatibility BC Math. Nativní ext-bcmath je proto volitelné, a to i u nově generovaných šablon, které aktivují kontroly JavaScript prostřednictvím předvolby Theme nebo Extreme.