PHPStan
De extensie blockstudio/phpstan voegt statische analyse toe aan Blockstudio-projecten. Tijdens de analyse worden blocktemplates, schemabestanden, instellingenpaden en hooknamen gevalideerd, zodat bugs worden opgespoord voordat ze tijdens runtime optreden.
Installatie
composer require --dev blockstudio/phpstan
Voor de template-typering van 7.7 en de uitgebreide blocktagcontroles is blockstudio/phpstan 0.1.9 of hoger en PHPStan 2.1.47 of hoger vereist. Werk het pakket afzonderlijk van de plugin bij:
composer require --dev blockstudio/phpstan:^0.1.9
De extensie wordt automatisch ontdekt via het extensie-installatieprogramma van PHPStan. Handmatige configuratie is niet nodig.
Wat wordt gecontroleerd?
Toegang tot templatevelden
Als een bestand PHP naast een block.json staat, valideert de extensie elke toegang tot $a['key'] aan de hand van de gedeclareerde attributen van het block.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
De extensie weet dat Blockstudio $a, $attributes, $b, $block, $c, $context, $content, $isEditor en $isPreview definieert, evenals de island-variabelen, voordat een template wordt opgenomen. Daarom worden directe uitlezingen zoals $a['title'] niet gemeld als mogelijk ongedefinieerd en wordt het type van $a afgeleid van de block.json naast de template. De structuur blijft behouden bij verfijning, zodat $a['label'] ?? '', isset( $a['cta']['target'] ) en $a['cta']['title'] !== null de gedeclareerde veldtypen behouden; een template die $a zelf toewijst, behoudt het toegewezen type. Voeg geen docblock /** @var array<string, mixed> $a */ toe: dat vervangt de structuur door een open array.
Veldsleutels volgen de flatteningsregels van Blockstudio tijdens runtime. tabs en anonieme containers van het type group zonder id zijn alleen voor de presentatie; hun onderliggende velden blijven daarom in de bovenliggende scope. Een benoemde groep voegt de groeps-ID als voorvoegsel toe aan de onderliggende sleutels:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Herbruikbare aangepaste velden
Verwijzingen naar bestandsgebonden custom/* worden uitgebreid voordat templatekeys en arraystructuren worden gecontroleerd. De extensie leest de bijbehorende field.json en past dezelfde regels toe voor idStructure, overrides, geneste verwijzingen, groepen, tabbladen en repeaters als 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 resulterende templatekeys zijn title en hero_description. Deze worden herkend in PHP, Twig, Blade, blocktags en afgeleide attribuutstructuren.
Ontbrekende, dubbelzinnige, ongeldige of cyclische bestandsgebonden definities veroorzaken een specifieke fout blockstudio.customField.*. De afhankelijke sleutelcontroles voor dat block worden overgeslagen, zodat één onopgeloste definitie geen reeks onterechte fouten over onbekende velden veroorzaakt.
Definities die alleen tijdens runtime via het filter blockstudio/fields PHP worden geregistreerd, kunnen niet worden afgeleid met statische analyse. Gebruik een definitie field.json als het veld templatekeys moet opleveren die statisch worden gecontroleerd.
Toegang tot Twig-templates
Twig-templates worden automatisch gescand. Annotatie is niet nodig.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Toegang tot Blade-templates
Blade-templates worden op dezelfde manier gescand.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Validatie van blocktags
Blocktags worden gevalideerd op de plekken waar Blockstudio ze uitleest: tags <bs:> en <block>, de voorvoegsel-tags die zijn geconfigureerd in blockTags.prefixes (zoals <acme-card>, opgelost in namespacevolgorde zoals tijdens runtime), en aliastags in blocktemplates van PHP, Twig en Blade, evenals in paginalay-outs. Ook paginabronnen onder pages/ (index.php, index.html, index.twig, index.blade.php) worden gecontroleerd, inclusief de elementen HTML die het project aan blocks koppelt. Ingebouwde blocks van UI zijn bekend wanneer ui.enabled is ingeschakeld.
<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) -->
Een attribuut wordt geaccepteerd wanneer het block het als veld declareert (inclusief aangepaste velden en velden die een getypeerd blockveld doorgeeft binnen zijn idStructure), of wanneer Blockstudio het doorgeeft aan het root-element van het block: data-*, aria-*, id, style, role, title, lang, dir, hidden en tabindex. In templates wordt elk attribuut html-* doorgegeven; in paginabronnen verwijst een voorvoegsel html- alleen naar een van de doorgegeven attributen. Alles daarbuiten wordt gemeld, vooral een niet-gedeclareerde class, omdat Blockstudio deze opslaat maar nooit weergeeft.
Tijdens runtime registreert het systeem elementkoppelingen en tagaliassen in PHP-filters. Statische analyse kan deze niet evalueren en leest ze daarom uit blockstudio.json. scanPhp controleert ook tags in andere projectbestanden PHP, zoals componentmarkeringen in modules, zonder daar onbekende blocks te melden:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Een element wordt gekoppeld aan een blocknaam of aan regels die op volgorde worden geprobeerd: de eerste regel waarvan het attribuut op het element staat, wordt gebruikt; een gewone blocknaam komt altijd overeen. Elementen die niet door het project worden gekoppeld, behouden hun core-block en worden niet gecontroleerd. Diagnostische meldingen gebruiken blockstudio.blockTag.unknown, blockstudio.blockTag.attribute en blockstudio.blockTag.class.
Typen van databasegegevens
Db::get() retourneert een getypeerde instantie op basis van het schema db.php. De recordstructuren worden automatisch afgeleid.
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
Verplichte velden zijn niet-nullable. Optionele velden zijn type|null. Een veld id (int) is altijd aanwezig. Dezelfde typering werkt voor de PHP-native buildersyntaxis Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Validatie van paden naar instellingen
Paden van Settings::get() worden gecontroleerd aan de hand van het bekende instellingenschema.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Validatie van hooknamen
Namen van hooks voor filters en acties Blockstudio worden gevalideerd.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dynamische instellinghooks zoals blockstudio/settings/tailwind/enabled zijn altijd toegestaan. Hooks die niet van blockstudio zijn, worden genegeerd.
Schemavalidatie
De extensie valideert elk schemabestand Blockstudio in het project.
block.json:
- Ontbrekend veld
name - Ontbrekend veld
type - Ontbrekende
idbij waardevelden die er een vereisen - Onbekende veldtypen
- Veldeigenschappen die het veldtype niet accepteert, zoals
"translat"in plaats van"translate", met de meest verwante bekende eigenschap als suggestie select/radio/checkboxzonderoptionsofpopulate- Dubbele veld-ID’s
- Een veld
tabsbinnen een herhaler, rechtstreeks of in een groep zonderid - Ongeldige declaraties van
pluginDependencies
Containervelden zoals group en tabs, plus veldverwijzingen van het type custom/*, kunnen id weglaten wanneer ze alleen andere velden uitbreiden of omwikkelen.
Veldeigenschappen worden gecontroleerd aan de hand van de eigenschappen die schemas/block.json voor elk ingebouwd veldtype declareert, plus de eigenschappen die elk veld accepteert. Wrapper-specifieke eigenschappen van custom/*-verwijzingen en veldtypen met projectgedefinieerde namespaces vallen buiten deze controle. De bestaande validatie van veldtypen en aangepaste verwijzingen blijft van toepassing. De identificatoren zijn blockstudio.blockJson.property en blockstudio.fieldJson.property.
Hierbij worden eigenschapsnamen gecontroleerd, niet alleen hun waarden: minimized is geldig voor een repeater, maar wordt gemeld bij een tekstveld. Het runtimegedrag van de plugin blijft ongewijzigd. Als een project bewust eigen metadata aan ingebouwde velden koppelt, onderdruk dan alleen deze meldingen zonder andere vormcontroles uit te schakelen:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Ingebouwde velden in een herbruikbare field.json worden nog steeds gecontroleerd, ook wanneer een custom/*-verwijzing eigen wrapperopties heeft. Extensiebestanden vallen buiten het bereik van deze diagnostiek voor eigenschapsnamen; extensiespecifieke regels voor set blijven geldig.
field.json (herbruikbare aangepaste velden):
- Ontbrekende
name - Ontbrekende of lege
attributes - Ongeldige attribuutobjecten of een ontbrekende veld-
type - Ontbrekende
idbij waardevvelden die er een vereisen - Onbekende veldtypen
- Veldeigenschappen die het veldtype niet accepteert
- Een
tabs-veld in een repeater, direct of in een groep zonderid - Ontbrekende, ambigue, ongeldige of cyclische geneste verwijzingen naar
custom/*
Extensie JSON (blockextensies in extensions/):
- Ontbrekende
name(doelblock) - Ontbrekende sleutel
blockstudio - Ontbrekende sleutel
blockstudio.extend
page.json (pagina’s op basis van bestanden):
- Ontbrekende
title - Ontbrekende
slug - Ongeldige waarden van
postStatus
db.php:
- Ontbrekende array
fields - Ongeldige veldtypen
- Ondersteunt zowel verouderde arrays als
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Ongeldige HTTP-methoden
- Verkeerde waarde voor
public(moettrue,falseof'open'zijn) - Ondersteunt zowel verouderde arrays als returns van objecten met attributen
cron.php:
- Ontbreekt
schedulebij geconfigureerde taken - Ontbreekt
callbackbij geconfigureerde taken - Ondersteunt zowel verouderde arrays als returns van objecten met attributen
blockstudio.json:
- Afgekorte booleans zoals
"tailwind": true(moeten de geneste objectnotatie{"enabled": true, "config": ""}gebruiken)
Configuratie
De extensie ontdekt standaard Blockstudio-bestanden in het geanalyseerde project.
Als een project blokken of herbruikbare velden uit een bibliotheek buiten de
projectroot gebruikt, voeg dan het bibliotheekpad toe aan blockstudioScanRoots. Het pad wordt
gecontroleerd op zowel block.json– als field.json-definities, zodat externe bloktags
en hun aangepaste velden samen kunnen worden gevalideerd.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Gebruik de standaardconfiguratie excludePaths van PHPStan om bestanden te negeren.
Analysevoorinstellingen
De automatisch ontdekte extensie blijft de compatibele basis. Blockstudio 7.6 voegt optionele lagen toe zonder bestaande projecten te wijzigen:
| Voorinstelling | Gedrag |
|---|---|
base.neon |
Analyse van bestaand schema, templates, hooks, instellingen en API. |
theme.neon |
Basis plus WordPress-themaroots, stijlheaders, Blockstudio-assets, selectorscope, standaardwaarden voor velden en grenzen voor herhalers. |
extreme-theme.neon |
Thema plus PHPStan max, onveilige PHP, outputescaping, Tailwind, JavaScript en Interactivity-controles API. |
wordpress-render.neon |
Extreem thema plus een live renderprobe WordPress die de aanroeper aanlevert. |
Bij installatie van blockstudio/phpstan wordt alleen de basisextensie ingeschakeld. Neem een optionele laag op in een bestaande configuratie van PHPStan:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths beheert de themascanner.
De standaard-excludePaths van PHPStan beheert onafhankelijk daarvan de analyse van PHP.
De instelling phpstan.excludePaths van de canonieke opdracht in blockstudio.json
(en de optie --exclude ervan) configureert beide lagen. Relatieve patronen worden
opgelost ten opzichte van elke geconfigureerde root, waardoor items zoals vendor/**
zowel de analyse van PHPStan als de projectscan van Blockstudio beperken.
Een patroon dat één map noemt, zoals _dist/** of node_modules/**,
sluit die map overal uit waar deze voorkomt, niet alleen naast de themaroot. Een
patroon met een slash, zoals assets/*/docs/**, blijft gekoppeld aan de root. Gegenereerde
blokassets staan in een map _dist binnen elk blok; daarom voorkomt de vorm met één map dat gecompileerde output wordt geanalyseerd.
Canonieke opdracht
Het pakket installeert vendor/bin/blockstudio-phpstan als uitvoerbaar analysebestand.
Het voert de voorinstelling base uit, tenzij een project een andere kiest. De installatie van het pakket schakelt dus niet vanzelf de lagen voor thema of extreem thema in:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
De voorinstellingen bevatten de extensie zelf. Voeg phpstan/extension-installer niet toe aan een project dat de canonieke opdracht uitvoert:
met het installatieprogramma aanwezig wordt extension.neon twee keer geladen en stopt PHPStan met “This file is included multiple times” voordat er iets wordt geanalyseerd.
De opdracht stelt PHPStan standaard in op een 1G-geheugenlimiet, zodat projecten die door Composer worden beheerd WordPress niet erven van een gebruikelijke limiet van 128M CLI. Geef na -- een expliciete optie PHPStan mee om deze te overschrijven, bijvoorbeeld -- --memory-limit=512M --no-progress.
Analyse invoeren in een bestaand project
Bij een project dat nog nooit is geanalyseerd, worden doorgaans bij de eerste
uitvoering bevindingen gerapporteerd. Verlaag de voorinstelling niet; genereer in plaats daarvan een PHPStan-baseline en verwijs phpstan.configuration naar een projectconfiguratie die deze bevat. Nieuwe code moet dan aan de volledige voorinstelling voldoen, terwijl de vastgelegde bevindingen buiten beeld blijven:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Behoud de regel level voor de voorinstellingen base en theme. De canonieke opdracht stelt voor deze voorinstellingen alleen niveau max in als er geen projectconfiguratie is opgenomen; zonder niveau stopt PHPStan met “No rules detected”. De voorinstelling extreme-theme stelt zelf niveau max in.
Relatieve paden worden opgelost vanaf blockstudio.json. Zowel de canonieke opdracht
als de beheerde commit-hook pikt het bestand op, zodat de hook nieuwe bevindingen blokkeert zonder dat eerst de achterstand hoeft te worden weggewerkt.
Bewaar projectbrede standaardwaarden voor opdrachten in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Relatieve roots worden opgelost vanaf het bestand waarin ze zijn gedeclareerd. Expliciete waarden van CLI vervangen de bijbehorende waarden van JSON. Geef --blockstudio-json path/to/project.json mee om een alternatieve configuratiebron te gebruiken. Ongeldige JSON, niet-ondersteunde sleutels in phpstan, ongeldige waarden en een ontbrekende expliciete bron leiden voorspelbaar tot afsluiten met code 2.
Kies een andere voorinstelling, voeg een projectconfiguratie toe, voeg herhaalbare roots en uitsluitingen toe, of vraag PHPStan om JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
De wrapper stelt de configuratie samen in de tijdelijke systeemmap en verwijdert deze bij afsluiten. Er worden geen gegenereerde configuraties, baselines, hooks of caches naar het geanalyseerde project geschreven. Aanroepers kunnen de normale cache van PHPStan nog steeds expliciet configureren.
De afsluitcode is:
0als de analyse slaagt1als PHPStan diagnoses rapporteert2bij onjuist gebruik, configuratieproblemen of problemen met de procesuitvoering
Beheerde commit-hook
Schakel de door Blockstudio beheerde hook in blockstudio.json in om de analyse van het extreme thema als commitblokkade voor de repository in te stellen:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Synchroniseer deze na het installeren van afhankelijkheden of het wijzigen van de instelling:
vendor/bin/blockstudio-githooks sync
De opdracht schrijft de gegenereerde pre-commit-hook en het eigendomsrecord in de gemeenschappelijke map van Git, stelt core.hooksPath in op de map met beheerde hooks en koppelt de eerder geconfigureerde pre-commit-hook veilig aan de nieuwe hook. Herhaalde synchronisaties vernieuwen alleen het gegenereerde bestand, waardoor pakketupgrades idempotent zijn.
Stel commit in op false, verwijder deze instelling of verwijder blockstudio.json en voer vervolgens sync uit om het vastgelegde hookpad te herstellen en alleen bestanden te verwijderen die eigendom zijn van Blockstudio. Je kunt ook uitvoeren:
vendor/bin/blockstudio-githooks remove
Bestanden die eigendom zijn van de gebruiker worden nooit overschreven of verwijderd. Als iemand core.hooksPath wijzigt nadat Blockstudio is ingeschakeld, behoudt de verwijdering die nieuwere instelling. De gegenereerde hook ondersteunt gekoppelde Git-checkouts en paden met spaties door de actieve repository en projectroot op het moment van de commit op te lossen. De hook voert de canonieke opdracht vanuit die root uit, zodat hetzelfde object phpstan interactieve uitvoeringen en commits beheert zonder dubbele gegenereerde argumenten.
De hook voert alleen vendor/bin/blockstudio-phpstan uit. Blockstudio voert geen formatter uit en de hook wijzigt nooit projectbestanden. Ontbrekende afhankelijkheden en analysefouten blokkeren de commit met een bruikbare foutmelding.
Live rendering van WordPress
De live laag is bewust expliciet. De aanroeper beheert de omgeving WordPress en levert een argv-array aan:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
De opdracht wordt zonder shell uitgevoerd en moet één JSON-object afdrukken:
{"ok":true}
Een probe kan een gerichte fout melden:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Niet-nul afsluitcodes, time-outs, ongeldige JSON en ok: false leveren blockstudio.wordpress.render op.
blockstudio.javascript.domContract meldt een [data-*]-attribuutselector die een script doorgeeft aan querySelector(), querySelectorAll(), closest() of matches() wanneer geen geanalyseerde markup dat attribuut bevat. Markup omvat elk PHP-, Twig-, Blade- en HTML-bestand en elke component van het type React .tsx en .jsx onder de geanalyseerde roots, met uitzondering van uitgesloten paden. Componenten worden geparseerd: JSX-attribuutnamen tellen mee, net als de tekenreekssleutels van objectliteralen. Daardoor voldoet een attribuutobject dat op een element wordt uitgespreid aan de selector, terwijl klassennamen en andere attribuutwaarden niet meetellen.
De Interactivity API-controles lezen dezelfde React-componenten. Een data-wp-interactive-namespace op een JSX-element geldt voor blockstudio.interactivity.orphan als een sjabloonverwijzing, en de data-wp-*-directives daarin worden opgelost aan de hand van de dichtstbijzijnde omvattende namespace of een prefix namespace:: in de waarde. Directives met een statische tekenreekswaarde, geschreven als een attribuut van het type JSX of als tekenreekssleutel van een attribuutobject, moeten verwijzen naar bestaande storehandlers en -paden (blockstudio.interactivity.handler, blockstudio.interactivity.binding), en storecode mag de attributen en klassen waaraan ze zijn gekoppeld niet wijzigen (blockstudio.interactivity.derivedState). React escapt attribuutwaarden, dus data-wp-context in een component wordt niet gemeld; dynamische waarden worden niet gecontroleerd. Namespaces onder bsui/ horen bij de meegeleverde UI-blokken, waarvan de stores met Blockstudio buiten de geanalyseerde roots worden meegeleverd. Daarom zijn het nooit verweesde namespaces.
Diagnostische identificaties
Nieuwe diagnoses van voorinstellingen behouden stabiele ID’s van blockstudio.*:
- Themstructuur:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Assets en velden:
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 - Interactiviteit:
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
Prestaties
De scanner accepteert gewone uitgepakte mappen, verwijdert dubbele roots, laat mappen met afhankelijkheden, builds en caches over, slaat bestandsinhoud in het geheugen op en sorteert diagnoses op voorspelbare wijze. Houd roots beperkt, sluit test- en gegenereerde mappen uit en stel een bestandslimiet in voor grote repositories. JavaScript en Tailwind kunnen onafhankelijk worden uitgeschakeld. Live rendering wordt alleen uitgevoerd als de bijbehorende voorinstelling is geselecteerd.
Diagnoses voor thema, JavaScript en Tailwind worden gerapporteerd via de resultaatcache van PHPStan. Na wijziging van alleen een block.json of een script kan een warme cache het vorige resultaat melden. Geef na -- --debug mee om de cache te omzeilen wanneer je zulke wijzigingen controleert.
Projectafspraken voor codeagents
Het pakket installeert een derde uitvoerbaar bestand, vendor/bin/blockstudio-agents. Dit schrijft een AGENTS.md met een beschrijving van het project waarin het wordt uitgevoerd. Dat heeft een codeagent nodig voordat deze iets aanraakt: wat het project maakt, welke Blockstudio-functies zijn ingeschakeld, wat de analyse afkeurt en welke opdrachten van toepassing zijn.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Niets in de uitvoer is een vast sjabloon. Elke regel is afgeleid van een van drie bronnen:
- De eigen bestanden van het project. Een thema met een header
style.css, blokken en pagina’s die op bestanden zijn gebaseerd, levert een ander document op dan een plugin die alleen blokken registreert. Aantallen, mappen, bloknaamruimten en templatel talen zijn wat de scanner daadwerkelijk heeft gevonden, met dezelfde roots en uitsluitingen als bij de analyse. blockstudio.json. Alleen ingeschakelde functies worden beschreven, met hun geconfigureerde waarden: voorvoegsels van bloktags en de naamruimten waarnaar deze verwijzen, Tailwind, de meegeleverde UI, de reset van editorassets, het cachepad, het prestatieprofiel, statische prerendering en de dynamische paden ervan, themastandaarden, Content Sync en de commit-hook.- De geselecteerde
phpstan.preset. De sectie over juistheid wordt laag voor laag uit de voorinstellingsbestanden zelf gelezen en vermeldt dus precies de regels die door die voorinstelling worden geregistreerd. Bijbaseworden de regels voor schema’s, templates, hooks en instellingen beschreven. Bijextreme-themeworden ook de regels voor de themastructuur, strikte PHPStan-vlaggen, onveilige PHP, outputescaping, Tailwind en JavaScript beschreven. Als een voorinstelling een regel krijgt, verandert het gegenereerde document mee.
De sectie met opdrachten volgt hetzelfde principe. wp bs prerender status verschijnt wanneer statische prerendering is ingeschakeld, vendor/bin/blockstudio-githooks sync wanneer githooks.commit is ingesteld en wp bs db schemas wanneer het project daadwerkelijk een db.php heeft.
| Optie | Gedrag |
|---|---|
--root <path> |
Projectroot (standaard: huidige map) |
--config <path> |
Pad naar blockstudio.json (standaard: <root>/blockstudio.json) |
--output <path> |
Contractpad (standaard: <root>/AGENTS.md) |
--stdout |
Druk het contract af in plaats van het te schrijven |
--check |
Sluit af met 1 als het contract op schijf verouderd is |
--force |
Vervang een bestand waarvan Blockstudio geen eigenaar is |
--check maakt van het contract een CI-controle, net zoals de commit-hook van de analyse een controle maakt:
vendor/bin/blockstudio-agents --check
Eigenaarschap
Het gegenereerde bestand bevat hetzelfde type marker als de beheerde commit-hook en dezelfde regel geldt: Blockstudio vervangt nooit een bestand dat het niet heeft geschreven. Een AGENTS.md dat al bestond voordat de opdracht werd geïnstalleerd, of dat een auteur handmatig heeft geschreven, wordt geweigerd met afsluitcode 2 en blijft onaangeroerd totdat --force wordt meegegeven.
Opnieuw genereren is veilig. Het bestand eindigt met een notitiegedeelte en de bytes tussen de markers daarvan blijven bij elke nieuwe generatie behouden:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
De afsluitcodes zijn 0 wanneer het contract wordt geschreven, actueel is of wordt afgedrukt, 1 wanneer --check een verouderd contract aantreft en 2 bij fouten in gebruik, configuratie of het bestandssysteem.
Vormen van veldtypen
De extensie zet elk veldtype Blockstudio om naar een concreet type PHP:
| Veldtype | Type PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (enkelvoudig) |
string|int |
select, checkbox (meervoudig) |
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 (enkelvoudig) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (meervoudig) |
list<array{id: int, url: string, ...}> |
group |
Benoemde groepen gebruiken underscore-prefixen; anonieme groepen worden afgevlakt naar het bovenliggende bereik |
repeater |
list<array{...child fields...}> |
tabs |
Afgevlakt naar het bovenliggende bereik |
API-stubs
De extensie bevat stubs voor de volledige openbare API van Blockstudio:
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()
Deze bieden aanvullen en typecontrole zonder dat de broncode van de plugin Blockstudio op je machine nodig is.
Vereisten
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(aanbevolen voor automatische detectie)
Het pakket installeert automatisch de compatibiliteitsprovider voor BC Math. Native ext-bcmath is daarom optioneel, ook voor nieuw gegenereerde thema’s die de controles JavaScript inschakelen via de thema- of extreemthema-voorinstelling.