PHPStan
Tillägget blockstudio/phpstan ger statisk analys till Blockstudio-projekt. Det validerar blockmallar, schemafiler, inställningssökvägar och hooknamn vid analystillfället, så att buggar upptäcks innan de når runtime.
Installation
composer require --dev blockstudio/phpstan
Malltypningen i 7.7 och de utökade kontrollerna av blocktaggar kräver blockstudio/phpstan 0.1.9 eller senare och PHPStan 2.1.47 eller senare. Uppdatera paketet separat från tillägget:
composer require --dev blockstudio/phpstan:^0.1.9
Tillägget upptäcks automatiskt via tilläggsinstalleraren i PHPStan. Ingen manuell konfiguration behövs.
Vad den kontrollerar
Åtkomst till mallfält
När en PHP-fil ligger bredvid en block.json validerar tillägget varje åtkomst till $a['key'] mot blockets deklarerade attribut.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Tillägget vet att Blockstudio definierar $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview och ö-variablerna innan det inkluderar en mall. Därför rapporteras inte direkta läsningar som $a['title'] som möjligen odefinierade, och typen för $a hämtas från block.json bredvid mallen. Strukturen bevaras vid typförfining, så $a['label'] ?? '', isset( $a['cta']['target'] ) och $a['cta']['title'] !== null behåller de deklarerade fälttyperna; en mall som tilldelar $a självt behåller den typ som tilldelades. Lägg inte till ett docblock av typen /** @var array<string, mixed> $a */: det ersätter strukturen med en öppen array.
Fältnycklar följer Blockstudios regler för utplattning vid körning. tabs och anonyma group-behållare utan id används bara för presentation, så deras underordnade fält ligger kvar i det överordnade omfånget. En namngiven grupp lägger till sitt ID som prefix till underordnade nycklar:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Återanvändbara anpassade fält
Filbaserade referenser till custom/* expanderas innan mallnycklar och arraystrukturer kontrolleras. Tillägget läser matchande field.json och tillämpar samma regler för idStructure, overrides, nästlade referenser, grupper, flikar och upprepningsfält som 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" }
}
}
]
}
}
De resulterande mallnycklarna är title och hero_description. De känns igen i PHP, Twig, Blade, blocktaggar och härledda attributstrukturer.
Saknade, tvetydiga, ogiltiga eller cykliska filbaserade definitioner ger ett specifikt blockstudio.customField.*-fel. Kontroller av beroende nycklar hoppas över för det blocket så att en olöst definition inte orsakar ytterligare en våg av falska fel om okända fält.
Definitioner som bara registreras vid körning via filtret blockstudio/fields PHP kan inte härledas med statisk analys. Använd en definition av typen field.json när fältet måste bidra med mallnycklar som kontrolleras statiskt.
Mallåtkomst för Twig
Mallar för Twig genomsöks automatiskt. Ingen annotering behövs.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Mallåtkomst för Blade
Mallar för Blade genomsöks på samma sätt.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Validering av blocktaggar
Blocktaggar valideras där Blockstudio läser dem: taggarna <bs:> och <block>, prefix-taggarna som konfigurerats i blockTags.prefixes (till exempel <acme-card>, som löses i namnrymdsordning liksom vid körning) och aliastaggar i blockmallarna PHP, Twig och Blade samt i sidlayouter. Sidkällor under pages/ (index.php, index.html, index.twig, index.blade.php) kontrolleras också, inklusive elementen HTML som projektet mappar till block. Medföljande UI-block känns igen när ui.enabled är aktiverat.
<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) -->
Ett attribut godkänns när blocket deklarerar det som ett fält (inklusive anpassade fält och fält som ett blocktypat fält vidarebefordrar under sitt idStructure), eller när Blockstudio vidarebefordrar det till blockets rotelement: data-*, aria-*, id, style, role, title, lang, dir, hidden och tabindex. I mallar släpps varje attribut i html-* igenom; i sidkällor anger ett html--prefix bara ett av de vidarebefordrade attributen. Allt annat rapporteras, framför allt ett odeklarerat class, eftersom Blockstudio lagrar det utan att någonsin rendera det.
Körningen registrerar elementmappningar och taggalias i PHP-filter, som statisk analys inte kan utvärdera, så analysen läser dem från blockstudio.json. scanPhp kontrollerar också taggar i andra PHP i projektet, till exempel komponentmarkering i moduler, utan att rapportera okända block där:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Ett element mappas till ett blocknamn eller till regler som prövas i ordning: den första regeln vars attribut elementet har vinner, och ett vanligt blocknamn matchar alltid. Element som projektet inte mappar behåller sitt kärnblock och kontrolleras inte. Diagnostik använder blockstudio.blockTag.unknown, blockstudio.blockTag.attribute och blockstudio.blockTag.class.
Typning av databasposter
Db::get() returnerar en typad instans baserad på schemat db.php. Poststrukturer härleds automatiskt.
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
Obligatoriska fält kan inte vara null. Valfria fält är type|null. Ett id-fält (int) finns alltid. Samma typning fungerar med den PHP-inbyggda byggarsyntaxen Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Validering av inställningssökvägar
Sökvägar till Settings::get() kontrolleras mot det kända inställningsschemat.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Validering av hooknamn
Hooknamn för filter och åtgärder i Blockstudio valideras.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dynamiska inställningshooks som blockstudio/settings/tailwind/enabled tillåts alltid. Hooks som inte hör till blockstudio ignoreras.
Schemavalidering
Tillägget validerar varje schemafil av typen Blockstudio i projektet.
block.json:
- Fältet
namesaknas - Fältet
typesaknas idsaknas för värdefält som kräver ett- Okända fälttyper
- Fältegenskaper som fälttypen inte stöder, till exempel
"translat"i stället för"translate", med närmast matchande kända egenskap som förslag select/radio/checkboxutanoptionsellerpopulate- Dubblerade fält-ID:n
- Ett
tabs-fält i en upprepningsgrupp, direkt eller i en grupp utanid - Ogiltiga
pluginDependencies-deklarationer
Behållarfält som group och tabs samt fältreferenser av typen custom/* kan utelämna id när de bara expanderar eller omsluter andra fält.
Fältegenskaper kontrolleras mot egenskaperna schemas/block.json deklarerar för varje inbyggd fälttyp, samt de egenskaper som alla fält godtar. Wrapper-specifika egenskaper på custom/*-referenser och projektspecifika namnrymda fälttyper omfattas inte av den här kontrollen. Validering av befintliga fälttyper och anpassade referenser gäller fortfarande. Identifierarna är blockstudio.blockJson.property och blockstudio.fieldJson.property.
Det här kontrollerar egenskapsnamn, inte bara deras värden: minimized är giltigt för ett repeaterfält men rapporteras för ett textfält. Pluginets körningsbeteende är oförändrat. Om ett projekt avsiktligt kopplar egna metadata till inbyggda fält kan du undertrycka endast dessa resultat utan att inaktivera andra formkontroller:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Inbyggda fält i en återanvändbar field.json kontrolleras fortfarande, även när en custom/*-referens har egna wrapper-alternativ. Tilläggsfiler omfattas inte av dessa diagnostikkontroller av egenskapsnamn; tilläggsspecifika regler för set gäller fortfarande.
field.json (återanvändbara anpassade fält):
- Saknar
name - Saknar eller har tomt
attributes - Ogiltiga attributobjekt eller saknar fältet
type - Saknar
idför värdefält som kräver ett sådant - Okända fälttyper
- Fältegenskaper som fälttypen inte godtar
- Ett fält av typen
tabsi ett repeaterfält, direkt eller i en grupp utanid - Saknade, tvetydiga, ogiltiga eller cykliska nästlade
custom/*-referenser
Tillägg JSON (blocktillägg i extensions/):
- Saknat
name(målblock) - Saknad nyckel
blockstudio - Saknad nyckel
blockstudio.extend
page.json (filbaserade sidor):
- Saknat
title - Saknat
slug - Ogiltiga värden för
postStatus
db.php:
- Saknad array för
fields - Ogiltiga fälttyper
- Stöder både äldre arrayer och
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Ogiltiga metoder för HTTP
- Felaktigt värde för
public(måste varatrue,falseeller'open') - Stöder både äldre arrayer och attributerade objektreturer
cron.php:
- Saknar
scheduleför konfigurerade uppgifter - Saknar
callbackför konfigurerade uppgifter - Stöder både äldre arrayer och attributförsedda objektreturer
blockstudio.json:
- Förkortade booleska värden som
"tailwind": true(måste använda det nästlade objektformatet{"enabled": true, "config": ""})
Konfiguration
Tillägget hittar som standard Blockstudio-filer i det analyserade projektet.
När ett projekt använder block eller återanvändbara fält från ett bibliotek utanför
projektroten lägger du till bibliotekssökvägen i blockstudioScanRoots. Sökvägen
skannas efter både block.json– och field.json-definitioner, så externa blocktaggar och deras anpassade fält kan valideras tillsammans.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Om du vill ignorera filer använder du standardkonfigurationen excludePaths för PHPStan.
Analysförinställningar
Det automatiskt upptäckta tillägget förblir den kompatibilitetssäkra basen. Blockstudio 7.6 lägger till valfria lager utan att ändra befintliga projekt:
| Förinställning | Beteende |
|---|---|
base.neon |
Analys av befintligt schema, mallar, hookar, inställningar och API. |
theme.neon |
Basen plus temarötter för WordPress, stilmallar, Blockstudio-resurser, selektorskopning, fältstandardvärden och gränser för upprepade fält. |
extreme-theme.neon |
Tema plus PHPStan max, osäkra PHP, utdataescaping, Tailwind, JavaScript och kontroller av Interactivity API. |
wordpress-render.neon |
Extremt tema plus en anroparstyrd aktiv renderingskontroll med WordPress. |
Installation av blockstudio/phpstan aktiverar bara bastillägget. Lägg till ett valfritt
lager i en befintlig PHPStan-konfiguration:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths styr temasökaren.
Standardkonfigurationen excludePaths för PHPStan styr analysen av PHP separat.
Inställningen phpstan.excludePaths för det kanoniska kommandot i blockstudio.json
(och dess alternativ --exclude) konfigurerar båda lagren. Relativa mönster löses
mot varje konfigurerad rot, så poster som vendor/** begränsar analysen av PHPStan
såväl som projektgenomsökningen för Blockstudio.
Ett mönster som anger en enskild katalog, till exempel _dist/** eller node_modules/**,
utesluter katalogen var den än förekommer, inte bara intill temaroten. Ett
mönster med snedstreck, till exempel assets/*/docs/**, förblir förankrat i
roten. Genererade blockresurser finns i en katalog _dist i varje block, så
formen med en enskild katalog är den som håller kompilerad utdata utanför analysen.
Kanoniskt kommando
Paketet installerar vendor/bin/blockstudio-phpstan som körbart analysprogram. Det kör förinställningen
base om inte projektet väljer en annan, så paketinstallationen aktiverar aldrig temalagret eller lagret för extrema teman på egen hand:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Förinställningarna inkluderar själva tillägget. Lägg inte till
phpstan/extension-installer i ett projekt som kör det kanoniska kommandot:
med installationsprogrammet närvarande läses extension.neon in två gånger och PHPStan avbryts
med ”This file is included multiple times” innan någon analys görs.
Kommandot ställer som standard in PHPStan på en minnesgräns på 1G, så Composer-hanterade
WordPress-projekt inte ärver en typisk gräns på 128M CLI. Skicka ett
uttryckligt alternativ PHPStan efter -- för att åsidosätta den, till exempel
-- --memory-limit=512M --no-progress.
Införa analys i ett befintligt projekt
Ett projekt som aldrig har analyserats rapporterar vanligtvis resultat vid den första
körningen. Sänk förinställningen inte; generera i stället en baslinje PHPStan och ange
phpstan.configuration till en projektkonfiguration som inkluderar den. Ny kod
kontrolleras då mot hela förinställningen, medan registrerade resultat inte är i vägen:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Behåll raden level för förinställningarna base och theme. Det kanoniska kommandot
ställer bara in nivån max för dem när ingen projektkonfiguration inkluderas, och
utan en nivå PHPStan avbryts körningen med ”No rules detected”. Förinställningen extreme-theme
ställer själv in nivån max.
Relativa sökvägar löses från blockstudio.json. Det kanoniska kommandot och den
hanterade commit-hooken läser båda in filen, så hooken stoppar nya resultat utan
att först kräva att eftersläpningen rensas.
Behåll projektomfattande standardvärden för kommandon i blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Relativa rötter löses från filen som anger dem. Uttryckliga värden för CLI
ersätter motsvarande värden för JSON. Skicka
--blockstudio-json path/to/project.json för en alternativ
konfigurationskälla. Felaktigt formaterad JSON, nycklar i phpstan som inte stöds, ogiltiga värden och en explicit källa som saknas ger ett deterministiskt fel med avslutningskod 2.
Välj en annan förinställning, inkludera en projektkonfiguration, lägg till återkommande rötter och undantag, eller be PHPStan om JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Omslaget sammanställer konfigurationen i systemets temporärkatalog och tar bort den vid avslut. Det skriver aldrig genererad konfiguration, baslinjer, hookar eller cachefiler i det analyserade projektet. Anropare kan fortfarande konfigurera PHPStan:s vanliga cache uttryckligen.
Avslutningskoderna är:
0när analysen godkänns1när PHPStan rapporterar diagnostik2vid felaktig användning, konfiguration eller processkörning
Hanterad commit-hook
Om du vill göra analysen av extrema teman till en spärr för repository-commits aktiverar du den hook som ägs av Blockstudio i blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Synkronisera den efter att du har installerat beroenden eller ändrat inställningen:
vendor/bin/blockstudio-githooks sync
Kommandot skriver sin genererade pre-commit-hook och ägarpost i
Gits gemensamma katalog, ställer in core.hooksPath på den hanterade hookkatalogen
och kedjar säkert ihop den tidigare konfigurerade pre-commit-hooken. Upprepade synkroniseringar
uppdaterar bara den genererade filen, så paketuppgraderingar är idempotenta.
Ställ in commit på false, ta bort den eller ta bort blockstudio.json och kör
sync för att återställa den registrerade hook-sökvägen och bara ta bort filer som ägs av Blockstudio.
Du kan också köra:
vendor/bin/blockstudio-githooks remove
Filer som ägs av användaren skrivs aldrig över eller tas bort. Om någon ändrar
core.hooksPath efter att Blockstudio har aktiverats bevaras den nyare
inställningen vid borttagning. Den genererade hooken stöder länkade Git-utcheckningar och sökvägar som innehåller
blanksteg genom att identifiera det aktiva repot och projektroten vid commit. Den
kör det kanoniska kommandot från den roten, så samma phpstan-objekt styr
interaktiva körningar och commits utan duplicerade genererade argument.
Hooken kör endast vendor/bin/blockstudio-phpstan. Blockstudio kör ingen
formaterare, och hooken skriver aldrig om projektfiler. Beroenden som saknas och
analysfel stoppar commiten med ett felmeddelande som går att åtgärda.
Aktiv rendering med WordPress
Det aktiva lagret är avsiktligt explicit. Anroparen äger miljön WordPress och tillhandahåller en argv-array:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Kommandot körs utan ett skal och måste skriva ut ett JSON-objekt:
{"ok":true}
En kontroll kan rapportera ett avgränsat fel:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Avslut med status som inte är noll, tidsgränsöverskridanden, felaktig JSON och ok: false ger
blockstudio.wordpress.render.
blockstudio.javascript.domContract rapporterar en attributväljare för [data-*] som ett skript skickar till querySelector(), querySelectorAll(), closest() eller matches() när inget analyserat märkspråk innehåller det attributet. Märkspråk omfattar alla filer av typen PHP, Twig, Blade och HTML samt alla React-komponenter av typen .tsx och .jsx under de analyserade rötterna, minus de undantagna sökvägarna. Komponenter parsas: JSX-attributnamn räknas, liksom strängnycklar i objektliteraler. Därför uppfyller ett attributobjekt som sprids ut på ett element väljaren, medan klassnamn och andra attributvärden inte gör det.
Interactivity API-kontrollerna läser samma React-komponenter. Ett data-wp-interactive-namnrymdsattribut på ett JSX-element räknas som en mallreferens för blockstudio.interactivity.orphan, och direktiven data-wp-* inuti det löses mot den närmast omslutande namnrymden eller ett namespace::-prefix i värdet. Direktiven med ett statiskt strängvärde, skrivna som ett JSX-attribut eller som en strängnyckel i ett attributobjekt, måste ange befintliga hanterare och sökvägar i lagret (blockstudio.interactivity.handler, blockstudio.interactivity.binding), och lagerkod får inte ändra attributen och klasserna som de binder till (blockstudio.interactivity.derivedState). React escape:ar attributvärden, så data-wp-context i en komponent rapporteras inte, och dynamiska värden kontrolleras inte. Namnrymder under bsui/ tillhör de medföljande UI-blocken, vars lager levereras med Blockstudio utanför de analyserade rötterna, så de är aldrig föräldralösa.
Diagnostikidentifierare
Ny diagnostik för förinställningar behåller stabila blockstudio.*-ID:n:
- Temastruktur:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Resurser och fält:
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 - Interaktivitet:
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
Prestanda
Skannern hanterar vanliga kataloger som materialiserats på disk, tar bort dubbletter bland rötter, hoppar över beroende-, bygg- och cacheträd, cachar filläsningar i minnet och sorterar diagnostik deterministiskt. Håll rötterna snäva, undanta testdata och genererade träd och ange en filgräns för stora repositorier. JavaScript och Tailwind kan inaktiveras oberoende av varandra. Aktiv rendering körs aldrig om inte dess förinställning har valts.
Diagnostik för tema, JavaScript och Tailwind rapporteras via resultatcachen för PHPStan.
Om du bara ändrar en block.json eller ett skript kan en varm
cache rapportera det tidigare resultatet. Skicka
--debug efter -- för att kringgå cachen när du verifierar sådana ändringar.
Projektavtal för kodningsagenter
Paketet installerar ett tredje körbart program, vendor/bin/blockstudio-agents. Det
skriver ett AGENTS.md som beskriver projektet det körs i, vilket en kodningsagent
behöver veta innan den ändrar något: vad projektet skapar, vilka Blockstudio-funktioner som är aktiverade, vad analysen kommer att avvisa och vilka kommandon som gäller.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Ingenting i utdata är en fast mall. Varje rad kommer från en av tre källor:
- Projektets egna filer. Ett tema med ett
style.css-huvud, block och filbaserade sidor ger ett annat dokument än ett tillägg som registrerar block och inget annat. Antal, kataloger, blocknamnrymder och mallspråk är det som skannern faktiskt hittade, med samma rötter och undantag som vid analysen. blockstudio.json. Endast aktiverade funktioner beskrivs, med sina konfigurerade värden: prefix för blocktaggar och namnrymderna de slås upp i, Tailwind, den medföljande UI, återställning av redigerarresurser, cachesökvägen, prestandaprofilen, statisk prerendering och dess dynamiska sökvägar, temats standardvärden, Content Sync och commit-hooken.- Den valda
phpstan.preset. Avsnittet om korrekthet läses från själva förinställningsfilerna, lager för lager, så att det listar exakt de regler som förinställningen registrerar. Vidbasebeskriver det reglerna för schema, mallar, hookar och inställningar. Vidextreme-themebeskriver det även reglerna för temastruktur, de strikta flaggorna PHPStan, osäkra PHP, utdataescaping, Tailwind och JavaScript. Om en regel läggs till i en förinställning uppdateras det genererade dokumentet i enlighet med detta.
Avsnittet om kommandon följer samma princip. wp bs prerender status
visas när statisk prerendering är aktiverad, vendor/bin/blockstudio-githooks sync när githooks.commit är inställt och wp bs db schemas när projektet
faktiskt har en db.php.
| Alternativ | Beteende |
|---|---|
--root <path> |
Projektrot (standard: aktuell katalog) |
--config <path> |
Sökväg till blockstudio.json (standard: <root>/blockstudio.json) |
--output <path> |
Avtalssökväg (standard: <root>/AGENTS.md) |
--stdout |
Skriv ut avtalet i stället för att skriva det till fil |
--check |
Avsluta med 1 om avtalet på disk inte är aktuellt |
--force |
Ersätt en fil som Blockstudio inte äger |
--check gör avtalet till en CI-spärr, på samma sätt som commit-hooken gör
analysen till en spärr:
vendor/bin/blockstudio-agents --check
Ägarskap
Den genererade filen har samma slags markör som den hanterade commit-hooken,
och samma regel gäller: Blockstudio ersätter aldrig en fil som det inte har skrivit.
En AGENTS.md som skapades innan kommandot, eller som en utvecklare skrev för hand, nekas med avslutningskod 2 och lämnas orörd tills --force skickas med.
Det är säkert att generera filen på nytt. Filen avslutas med ett anteckningsområde, och byten mellan markörerna bevaras vid varje ny generering:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Avslutningskoderna är 0 när avtalet skrivs, är aktuellt eller skrivs ut, 1 när
--check hittar ett inaktuellt avtal och 2 vid fel i användning, konfiguration eller
filsystem.
Fälttypernas former
Tillägget mappar varje fälttyp i Blockstudio till en konkret typ i PHP:
| Fälttyp | PHP-typ |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (enkel) |
string|int |
select, checkbox (flera) |
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 (enkel) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (flera) |
list<array{id: int, url: string, ...}> |
group |
Namngivna grupper använder understreck som prefix; anonyma grupper plattas ut i förälderns omfång |
repeater |
list<array{...child fields...}> |
tabs |
Plattas ut i förälderns omfång |
API-stubbar
Tillägget innehåller stubbar för hela det offentliga 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()
Dessa ger komplettering och typkontroll utan att du behöver ha Blockstudio-tilläggets källkod på din dator.
Krav
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(rekommenderas för automatisk upptäckt)
Paketet installerar automatiskt sin BC Math-kompatibilitetsleverantör. Inbyggt
ext-bcmath är därför valfritt, även för nyskapade teman som aktiverar kontrollerna för JavaScript via tema- eller extremförinställningen.