PHPStan
L’estensione blockstudio/phpstan aggiunge l’analisi statica ai progetti Blockstudio. Convalida i template dei blocchi, i file schema, i percorsi delle impostazioni e i nomi degli hook durante l’analisi, individuando i bug prima che si verifichino a runtime.
Installazione
composer require --dev blockstudio/phpstan
La tipizzazione dei template e i controlli estesi dei tag dei blocchi della versione 7.7 richiedono blockstudio/phpstan 0.1.9 o versione successiva e PHPStan 2.1.47 o versione successiva. Aggiornate il pacchetto separatamente dal plugin:
composer require --dev blockstudio/phpstan:^0.1.9
L’estensione viene rilevata automaticamente tramite il programma di installazione delle estensioni di PHPStan. Non serve alcuna configurazione manuale.
Controlli disponibili
Accesso ai campi dei template
Quando un file PHP si trova accanto a un block.json, l’estensione convalida ogni accesso a $a['key'] in base agli attributi dichiarati del blocco.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
L’estensione sa che Blockstudio definisce $a, $attributes, $b,
$block, $c, $context, $content, $isEditor, $isPreview e le
variabili island prima di includere un template: perciò, letture dirette come
$a['title'] non vengono segnalate come potenzialmente non definite, e il tipo di $a viene dedotto dal block.json accanto al template. La struttura resta invariata anche dopo il restringimento del tipo, perciò $a['label'] ?? '', isset( $a['cta']['target'] ) e
$a['cta']['title'] !== null mantengono i tipi dei campi dichiarati; un template che assegna un valore a $a mantiene il tipo assegnato. Non aggiungete un
commento docblock /** @var array<string, mixed> $a */: sostituisce questa struttura con un
array aperto.
Le chiavi dei campi seguono le regole di appiattimento a runtime di Blockstudio. I contenitori tabs e group anonimi senza un id servono solo per la presentazione, quindi i relativi campi figli rimangono nell’ambito del genitore. Un gruppo denominato aggiunge il proprio ID come prefisso alle chiavi dei campi figli:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Campi personalizzati riutilizzabili
I riferimenti custom/* basati su file vengono espansi prima di controllare le chiavi dei template e le strutture degli array. L’estensione legge il field.json corrispondente e applica le stesse regole per idStructure, overrides, i riferimenti annidati, i gruppi, le schede e i repeater di 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" }
}
}
]
}
}
Le chiavi dei template risultanti sono title e hero_description. Vengono riconosciute in PHP, Twig, Blade, nei tag dei blocchi e nelle strutture degli attributi dedotte.
Le definizioni basate su file mancanti, ambigue, non valide o cicliche producono un errore specifico blockstudio.customField.*. I controlli delle chiavi dipendenti vengono ignorati per quel blocco, così una definizione irrisolta non genera una seconda serie di falsi errori relativi a campi sconosciuti.
Le definizioni registrate solo a runtime tramite il filtro blockstudio/fields PHP non possono essere dedotte dall’analisi statica. Usate una definizione field.json se il campo deve aggiungere chiavi dei template sottoposte a controlli statici.
Accesso ai template Twig
I template Twig vengono analizzati automaticamente. Non servono annotazioni.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Accesso ai template Blade
I template Blade vengono analizzati allo stesso modo.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Convalida dei tag dei blocchi
I tag dei blocchi vengono convalidati nei punti in cui Blockstudio li legge: nei tag <bs:> e <block>, nei tag con prefisso configurati in blockTags.prefixes (come <acme-card>, risolti in ordine di namespace come a runtime) e nei tag alias, all’interno dei template dei blocchi PHP, Twig e Blade, nonché nei layout delle pagine. Vengono controllate anche le origini delle pagine sotto pages/ (index.php, index.html, index.twig, index.blade.php), compresi gli elementi HTML che il progetto associa ai blocchi. I blocchi UI inclusi sono riconosciuti quando ui.enabled è attivo.
<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) -->
Un attributo è accettato se il blocco lo dichiara come campo (compresi i campi personalizzati e quelli inoltrati da un campo tipizzato come blocco tramite il suo idStructure), oppure se Blockstudio lo inoltra all’elemento radice del blocco: data-*, aria-*, id, style, role, title, lang, dir, hidden e tabindex. Nei template vengono inoltrati tutti gli attributi html-*; nelle origini delle pagine, un prefisso html- indica solo uno degli attributi inoltrati. Qualsiasi altro attributo viene segnalato, soprattutto un class non dichiarato, perché Blockstudio lo memorizza ma non lo visualizza.
A runtime, gli elementi vengono associati ai tag alias tramite i filtri PHP, che l’analisi statica non può valutare, perciò l’analisi li legge da blockstudio.json. scanPhp controlla anche i tag in altri PHP del progetto, come il markup dei componenti nei moduli, senza segnalare blocchi sconosciuti al loro interno:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Un elemento viene associato a un nome di blocco o a regole valutate in ordine: vince la prima regola il cui attributo è presente sull’elemento, mentre un semplice nome di blocco corrisponde sempre. Gli elementi non associati dal progetto mantengono il proprio blocco core e non vengono controllati. I diagnostici usano blockstudio.blockTag.unknown, blockstudio.blockTag.attribute e blockstudio.blockTag.class.
Tipizzazione dei record del database
Db::get() restituisce un’istanza tipizzata in base allo schema db.php. Le strutture dei record vengono dedotte automaticamente.
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
I campi obbligatori non sono nullable. I campi facoltativi sono type|null. Un campo id (int) è sempre presente. La stessa tipizzazione funziona con la sintassi PHP nativa di Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Convalida dei percorsi delle impostazioni
I percorsi Settings::get() vengono controllati in base allo schema delle impostazioni noto.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Convalida dei nomi degli hook
I nomi dei filtri Blockstudio e degli hook action vengono convalidati.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Gli hook per le impostazioni dinamiche, come blockstudio/settings/tailwind/enabled, sono sempre consentiti. Gli hook non blockstudio vengono ignorati.
Convalida degli schemi
L’estensione convalida ogni file schema Blockstudio del progetto.
block.json:
- Campo
namemancante - Campo
typemancante idmancante nei campi di valore che ne richiedono uno- Tipi di campo sconosciuti
- Proprietà del campo non accettate dal tipo di campo, ad esempio
"translat"invece di"translate", con il suggerimento della proprietà nota più simile select/radio/checkboxsenzaoptionsopopulate- ID di campo duplicati
- Campo
tabsall’interno di un repeater, direttamente o in un gruppo senzaid - Dichiarazioni
pluginDependenciesnon valide
I campi contenitore, come group e tabs, e i riferimenti ai campi custom/* possono omettere id se servono solo a espandere o racchiudere altri campi.
Le proprietà dei campi vengono confrontate con quelle che schemas/block.json dichiara per ogni tipo di campo integrato, oltre che con le proprietà accettate da tutti i campi. Le proprietà specifiche dei wrapper nelle referenze custom/* e i tipi di campo con namespace definiti dal progetto non rientrano in questo controllo. Restano valide le verifiche esistenti sui tipi di campo e sulle referenze personalizzate. Gli identificatori sono blockstudio.blockJson.property e blockstudio.fieldJson.property.
Questo controllo riguarda i nomi delle proprietà, non solo i loro valori: minimized è valido per un repeater, ma viene segnalato su un campo di testo. Il comportamento del plugin in fase di esecuzione non cambia. Se un progetto aggiunge intenzionalmente metadati personalizzati ai campi integrati, sopprimete solo queste segnalazioni senza disattivare gli altri controlli sulla struttura:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
I campi integrati all’interno di un field.json riutilizzabile vengono comunque controllati, anche quando una referenza custom/* ha proprie opzioni wrapper. I file di estensione non rientrano nell’ambito di queste diagnostiche sui nomi delle proprietà; le regole set specifiche dell’estensione restano valide.
field.json (campi personalizzati riutilizzabili):
namemancanteattributesmancante o vuoto- Oggetti attributo non validi o
typedel campo mancante idmancante nei campi valore che ne richiedono uno- Tipi di campo sconosciuti
- Proprietà non accettate dal tipo di campo
- Un campo
tabsall’interno di un repeater, direttamente o in un gruppo senzaid - Referenze
custom/*annidate mancanti, ambigue, non valide o cicliche
Estensione JSON (estensioni dei blocchi in extensions/):
namemancante (blocco di destinazione)- Chiave
blockstudiomancante - Chiave
blockstudio.extendmancante
page.json (pagine basate su file):
- Manca
title - Manca
slug - Valori
postStatusnon validi
db.php:
- Array
fieldsmancante - Tipi di campo non validi
- Supporta sia gli array legacy sia
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Metodi HTTP non validi
- Valore
publicerrato (deve esseretrue,falseo'open') - Supporta sia gli array legacy sia i valori restituiti da oggetti con attributi
cron.php:
schedulemancanti nelle attività configuratecallbackmancanti nelle attività configurate- Supporta sia gli array legacy sia i valori restituiti come oggetti con attributi
blockstudio.json:
- Valori booleani abbreviati come
"tailwind": true(è necessario usare il formato a oggetto annidato{"enabled": true, "config": ""})
Configurazione
Per impostazione predefinita, l’estensione rileva i file Blockstudio nel progetto analizzato.
Se un progetto usa blocchi o campi riutilizzabili di una libreria esterna alla
radice del progetto, aggiungete il percorso della libreria a blockstudioScanRoots. Il percorso viene
analizzato alla ricerca sia di definizioni block.json sia di field.json, così da poter convalidare insieme i tag dei blocchi esterni e i relativi campi personalizzati.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Per ignorare i file, usate la configurazione standard excludePaths di PHPStan.
Preset di analisi
L’estensione rilevata automaticamente resta la base sicura per la compatibilità. Blockstudio 7.6 aggiunge livelli facoltativi senza modificare i progetti esistenti:
| Preset | Comportamento |
|---|---|
base.neon |
Analisi dello schema, dei template, degli hook, delle impostazioni e di API esistenti. |
theme.neon |
Base più radici del tema WordPress, intestazioni degli stili, risorse Blockstudio, ambito dei selettori, valori predefiniti dei campi e limiti dei ripetitori. |
extreme-theme.neon |
Tema più PHPStan max, PHP non sicuro, escaping dell’output, Tailwind, JavaScript e controlli di Interactivity API. |
wordpress-render.neon |
Tema estremo più una verifica di rendering live WordPress fornita dal chiamante. |
L’installazione di blockstudio/phpstan abilita solo l’estensione di base. Includete
un livello facoltativo nella configurazione PHPStan esistente:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths controlla lo scanner del tema.
La configurazione standard excludePaths di PHPStan controlla in modo indipendente l’analisi di PHP.
L’impostazione phpstan.excludePaths del comando canonico in blockstudio.json
(e la relativa opzione --exclude) configura entrambi i livelli. I pattern relativi vengono risolti
rispetto a ogni radice configurata, quindi voci come vendor/** limitano sia l’analisi di PHPStan sia la scansione del progetto di Blockstudio.
Un pattern che indica una singola directory, come _dist/** o node_modules/**,
esclude quella directory ovunque si trovi, non solo accanto alla radice del tema. Un
pattern contenente una barra, come assets/*/docs/**, resta ancorato alla
radice. Le risorse dei blocchi generate si trovano in una directory _dist all’interno di ciascun blocco, quindi
la forma con la singola directory esclude dall’analisi l’output compilato.
Comando canonico
Il pacchetto installa vendor/bin/blockstudio-phpstan come eseguibile per l’analisi.
Esegue il preset base, a meno che il progetto non ne selezioni un altro; l’installazione del pacchetto, quindi, non abilita da sola i livelli tema o tema estremo:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
I preset includono direttamente l’estensione. Non aggiungete
phpstan/extension-installer a un progetto che esegue il comando canonico:
se l’installer è presente, extension.neon viene caricato due volte e PHPStan si interrompe
con “This file is included multiple times” prima di analizzare alcunché.
Per impostazione predefinita, il comando imposta PHPStan su un limite di memoria 1G, affinché i progetti WordPress gestiti da Composer non ereditino il limite CLI tipico di 128M. Passate un’opzione PHPStan esplicita dopo -- per sovrascriverlo, ad esempio -- --memory-limit=512M --no-progress.
Aggiungere l’analisi a un progetto esistente
Un progetto mai analizzato in precedenza in genere segnala problemi alla prima
esecuzione. Invece di ridurre il preset, generate una baseline PHPStan e indicate
phpstan.configuration una configurazione di progetto che la includa. Il nuovo codice
sarà quindi soggetto all’intero preset, mentre i problemi già registrati non saranno d’intralcio:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Mantenete la riga level per i preset base e theme. Il comando canonico
imposta il livello max per questi preset solo se non è inclusa alcuna configurazione di progetto; senza un livello PHPStan si interrompe con “No rules detected”. Il preset extreme-theme imposta autonomamente il livello max.
I percorsi relativi sono risolti a partire da blockstudio.json. Il comando canonico e l’hook di commit gestito rilevano entrambi il file, così l’hook blocca nuovi problemi senza richiedere prima di eliminare quelli arretrati.
Mantenete in blockstudio.json le impostazioni predefinite del comando valide per tutto il progetto:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Le radici relative sono risolte a partire dal file che le dichiara. I valori espliciti di CLI sostituiscono i corrispondenti valori di JSON. Passate
--blockstudio-json path/to/project.json per indicare una sorgente di configurazione alternativa.
Un JSON malformato, chiavi phpstan non supportate, valori non validi e l’assenza di una sorgente esplicita causano un errore deterministico con codice di uscita 2.
Selezionate un altro preset, includete una configurazione di progetto, aggiungete radici ed esclusioni ripetibili oppure chiedete a PHPStan di mostrare JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Il wrapper compone la configurazione nella directory temporanea di sistema e la elimina all’uscita. Non scrive configurazioni generate, baseline, hook o cache nel progetto analizzato. I chiamanti possono comunque configurare esplicitamente la normale cache di PHPStan.
Il contratto dei codici di uscita è:
0se l’analisi ha esito positivo1se PHPStan segnala problemi2per uso, configurazione o esecuzione del processo non validi
Hook di commit gestito
Per rendere l’analisi del tema estremo un controllo obbligatorio al commit del repository, abilitate l’hook gestito da Blockstudio in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Sincronizzatelo dopo aver installato le dipendenze o modificato l’impostazione:
vendor/bin/blockstudio-githooks sync
Il comando scrive l’hook pre-commit generato e il record di proprietà nella directory comune di Git, imposta core.hooksPath sulla directory dell’hook gestito e concatena in sicurezza l’hook pre-commit configurato in precedenza. Le sincronizzazioni ripetute aggiornano solo il file generato, quindi gli aggiornamenti del pacchetto sono idempotenti.
Impostate commit su false, rimuovetela oppure rimuovete blockstudio.json, quindi eseguite
sync per ripristinare il percorso dell’hook registrato ed eliminare solo i file gestiti da Blockstudio. Potete anche eseguire:
vendor/bin/blockstudio-githooks remove
I file gestiti dall’utente non vengono mai sovrascritti né eliminati. Se qualcuno modifica
core.hooksPath dopo aver abilitato Blockstudio, la rimozione conserva
l’impostazione più recente. L’hook generato supporta checkout Git collegati e percorsi contenenti spazi, risolvendo il repository attivo e la radice del progetto al momento del commit. Esegue il comando canonico da quella radice, così lo stesso oggetto phpstan controlla le esecuzioni interattive e i commit senza duplicare gli argomenti generati.
L’hook esegue solo vendor/bin/blockstudio-phpstan. Blockstudio non esegue un
formattatore e l’hook non riscrive mai i file del progetto. Dipendenze mancanti ed errori di analisi bloccano il commit con un messaggio chiaro su come procedere.
Rendering live di WordPress
Il livello live è volutamente esplicito. Il chiamante gestisce l’ambiente WordPress e fornisce un array argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Il comando viene eseguito senza shell e deve stampare un oggetto JSON:
{"ok":true}
Una verifica può segnalare un errore specifico:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Le uscite diverse da zero, i timeout, i file JSON malformati e ok: false generano
blockstudio.wordpress.render.
blockstudio.javascript.domContract segnala un selettore di attributo [data-*] passato da uno script a querySelector(), querySelectorAll(), closest() o matches(), quando nessun markup analizzato contiene quell’attributo. Il markup comprende tutti i file PHP, Twig, Blade e HTML e tutti i componenti React .tsx e .jsx nelle radici analizzate, esclusi i percorsi indicati. I componenti vengono analizzati: contano i nomi degli attributi JSX e anche le chiavi stringa degli oggetti letterali. Quindi, un oggetto attributo distribuito su un elemento soddisfa il selettore, mentre i nomi delle classi e gli altri valori degli attributi non lo fanno.
I controlli di Interactivity API leggono gli stessi componenti React. Un namespace data-wp-interactive su un elemento JSX conta come referenza a un template per blockstudio.interactivity.orphan, e le direttive data-wp-* al suo interno vengono risolte usando il namespace antenato più vicino oppure un prefisso namespace:: nel valore. Le direttive con un valore stringa statico, scritte come attributo JSX o come chiave stringa di un oggetto attributo, devono indicare gestori e percorsi esistenti nello store (blockstudio.interactivity.handler, blockstudio.interactivity.binding), e il codice dello store non deve modificare gli attributi e le classi a cui sono associate (blockstudio.interactivity.derivedState). React esegue l’escape dei valori degli attributi, quindi data-wp-context in un componente non viene segnalato; i valori dinamici non vengono controllati. I namespace sotto bsui/ appartengono ai blocchi UI inclusi, i cui store sono distribuiti con Blockstudio al di fuori delle radici analizzate, quindi non sono mai orfani.
Identificatori diagnostici
Le nuove diagnostiche dei preset mantengono ID blockstudio.* stabili:
- Struttura del tema:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Risorse e campi:
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 - Interattività:
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
Prestazioni
Lo scanner accetta directory ordinarie già materializzate, deduplica le radici, salta le directory di dipendenze, build e cache, memorizza in cache le letture dei file in memoria e ordina le diagnostiche in modo deterministico. Mantenete le radici circoscritte, escludete fixture e directory generate e impostate un limite di file per i repository di grandi dimensioni. JavaScript e Tailwind possono essere disabilitati indipendentemente. Il rendering live viene eseguito solo se si seleziona il relativo preset.
Le diagnostiche di tema, JavaScript e Tailwind vengono segnalate tramite la cache dei risultati di PHPStan. Dopo aver modificato solo un block.json o uno script, una cache ancora valida può restituire il risultato precedente. Passate
--debug dopo -- per ignorare la cache durante la verifica di queste modifiche.
Contratto del progetto per gli agenti di programmazione
Il pacchetto installa un terzo eseguibile, vendor/bin/blockstudio-agents. Scrive un file AGENTS.md che descrive il progetto in cui viene eseguito e fornisce agli agenti di programmazione le informazioni necessarie prima di intervenire: cosa sviluppano gli autori del progetto, quali funzionalità Blockstudio sono abilitate, quali problemi verranno rilevati dall’analisi e quali comandi sono disponibili.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Nessuna riga dell’output proviene da un modello fisso. Ogni riga deriva da una di queste tre fonti:
- I file del progetto. Un tema con intestazione
style.css, blocchi e pagine basate su file produce un documento diverso da quello di un plugin che registra solo blocchi. Conteggi, directory, namespace dei blocchi e linguaggi dei template corrispondono a quanto rilevato dallo scanner, che usa le stesse radici ed esclusioni dell’analisi. blockstudio.json. Vengono descritte solo le funzionalità abilitate, con i relativi valori configurati: prefissi dei tag dei blocchi e i namespace a cui fanno riferimento, Tailwind, il pacchetto UI, il ripristino delle risorse dell’editor, il percorso della cache, il profilo delle prestazioni, il prerendering statico e i relativi percorsi dinamici, i valori predefiniti del tema, Content Sync e l’hook di commit.- Il
phpstan.presetselezionato. La sezione sulla correttezza viene ricavata direttamente dai file dei preset, livello per livello, e riporta quindi esattamente le regole registrate dal preset. Conbasedescrive le regole relative a schema, template, hook e impostazioni. Conextreme-themedescrive anche le regole sulla struttura del tema, i flag PHPStan rigorosi, PHP non sicuro, l’escaping dell’output, Tailwind e JavaScript. Quando un preset acquisisce una nuova regola, anche il documento generato viene aggiornato.
La sezione dei comandi segue lo stesso principio. wp bs prerender status
compare se è abilitato il prerendering statico, vendor/bin/blockstudio-githooks sync se è impostato githooks.commit e wp bs db schemas se il progetto contiene effettivamente un db.php.
| Opzione | Comportamento |
|---|---|
--root <path> |
Radice del progetto (predefinita: directory corrente) |
--config <path> |
Percorso blockstudio.json (predefinito: <root>/blockstudio.json) |
--output <path> |
Percorso del contratto (predefinito: <root>/AGENTS.md) |
--stdout |
Stampa il contratto invece di scriverlo |
--check |
Esce con codice 1 se il contratto su disco non è aggiornato |
--force |
Sostituisce un file che Blockstudio non gestisce |
--check rende il contratto un controllo CI, proprio come l’hook di commit rende obbligatoria l’analisi:
vendor/bin/blockstudio-agents --check
Proprietà
Il file generato contiene un contrassegno dello stesso tipo di quello dell’hook di commit gestito; vale la stessa regola: Blockstudio non sostituisce mai un file che non ha scritto.
Se un file AGENTS.md esisteva già prima del comando o è stato scritto manualmente da un autore, l’operazione viene rifiutata con codice di uscita 2 e il file resta intatto finché non viene passato --force.
Rigenerare il file è sicuro. Il file termina con una sezione per le note e i byte compresi tra i relativi contrassegni vengono conservati a ogni rigenerazione:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
I codici di uscita sono 0 quando il contratto viene scritto, è aggiornato o viene stampato, 1 quando --check rileva un contratto non aggiornato e 2 in caso di errori di utilizzo, configurazione o filesystem.
Strutture dei tipi di campo
L’estensione associa ogni tipo di campo Blockstudio a un tipo concreto PHP:
| Tipo di campo | Tipo PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (singolo) |
string|int |
select, checkbox (multiplo) |
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 (singolo) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (multiplo) |
list<array{id: int, url: string, ...}> |
group |
I gruppi con nome usano prefissi underscore; i gruppi anonimi vengono appiattiti nell’ambito genitore |
repeater |
list<array{...child fields...}> |
tabs |
Appiattito nell’ambito genitore |
Stub di API
L’estensione include stub per l’intera Blockstudio pubblica di 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()
Questi forniscono completamento automatico e controllo dei tipi senza dover avere il codice sorgente del plugin Blockstudio sul computer.
Requisiti
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(consigliato per il rilevamento automatico)
Il pacchetto installa automaticamente il proprio provider di compatibilità BC Math. Pertanto
ext-bcmath è facoltativo, anche per i nuovi temi generati che abilitano i controlli JavaScript tramite il preset tema o tema estremo.