PHPStan
Extensia blockstudio/phpstan aduce analiza statică în proiectele Blockstudio. Validează șabloanele blocurilor, fișierele de schemă, căile setărilor și numele hookurilor în timpul analizei, identificând erorile înainte să ajungă la runtime.
Instalare
composer require --dev blockstudio/phpstan
Verificarea tipurilor șabloanelor din versiunea 7.7 și verificările extinse ale etichetelor de blocuri necesită blockstudio/phpstan 0.1.9 sau o versiune mai nouă și PHPStan 2.1.47 sau o versiune mai nouă. Actualizați pachetul separat de plugin:
composer require --dev blockstudio/phpstan:^0.1.9
Extensia este descoperită automat prin programul de instalare a extensiilor al PHPStan. Nu este necesară configurarea manuală.
Ce verifică
Accesarea câmpurilor din șabloane
Când un fișier PHP se află lângă un block.json, extensia validează fiecare acces $a['key'] în raport cu atributele declarate ale blocului.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Extensia știe că Blockstudio definește $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview și variabilele insulei înainte de a include un șablon, așa că citirile directe precum $a['title'] nu sunt raportate ca posibil nedefinite, iar tipul lui $a este dedus din block.json de lângă șablon. Structura se păstrează la restrângerea tipurilor, astfel încât $a['label'] ?? '', isset( $a['cta']['target'] ) și $a['cta']['title'] !== null păstrează tipurile de câmp declarate; un șablon care atribuie o valoare lui $a păstrează tipul atribuit. Nu adăugați un docblock /** @var array<string, mixed> $a */: acesta înlocuiește structura cu un array deschis.
Cheile câmpurilor respectă regulile de aplatizare la runtime ale Blockstudio. Containerele tabs și group anonime, fără un id, servesc doar prezentării, astfel încât câmpurile lor copil rămân în domeniul părinte. Un grup cu nume adaugă ID-ul grupului ca prefix la cheile câmpurilor copil:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Câmpuri personalizate reutilizabile
Referințele custom/* bazate pe fișiere sunt extinse înainte de verificarea cheilor șablonului și a structurilor array-urilor. Extensia citește field.json corespunzător și aplică aceleași reguli pentru idStructure, overrides, referințe imbricate, grupuri, file și repetoare ca 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" }
}
}
]
}
}
Cheile șablonului rezultate sunt title și hero_description. Acestea sunt recunoscute în PHP, Twig, Blade, etichetele blocurilor și structurile atributelor deduse.
Definițiile bazate pe fișiere care lipsesc, sunt ambigue, invalide sau ciclice generează o eroare specifică blockstudio.customField.*. Verificările cheilor dependente sunt omise pentru acel bloc, astfel încât o definiție nerezolvată să nu genereze o a doua serie de erori false pentru câmpuri necunoscute.
Definițiile înregistrate doar la runtime prin filtrul blockstudio/fields PHP nu pot fi deduse prin analiză statică. Folosiți o definiție field.json când câmpul trebuie să contribuie la cheile șablonului verificate static.
Accesarea șabloanelor Twig
Șabloanele Twig sunt scanate automat. Nu este necesară nicio adnotare.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Accesarea șabloanelor Blade
Șabloanele Blade sunt scanate în același mod.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Validarea etichetelor de blocuri
Etichetele de blocuri sunt validate acolo unde Blockstudio le citește: etichetele <bs:> și <block>, etichetele cu prefix configurate în blockTags.prefixes (precum <acme-card>, rezolvate în ordinea spațiilor de nume, ca la runtime) și etichetele alias din șabloanele de blocuri PHP, Twig și Blade, precum și din machetele paginilor. Sunt verificate și sursele paginilor din pages/ în jos (index.php, index.html, index.twig, index.blade.php), inclusiv elementele HTML pe care proiectul le mapează la blocuri. Blocurile UI incluse în pachet sunt recunoscute când ui.enabled este activat.
<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 atribut este acceptat dacă blocul îl declară drept câmp (inclusiv câmpurile personalizate și câmpurile pe care un câmp tipizat ca bloc le transmite mai departe sub idStructure) sau dacă Blockstudio îl transmite elementului rădăcină al blocului: data-*, aria-*, id, style, role, title, lang, dir, hidden și tabindex. În șabloane, fiecare atribut html-* este transmis mai departe; în sursele paginilor, un prefix html- denumește doar unul dintre atributele transmise. Orice altceva, mai ales un class nedeclarat, este raportat, deoarece Blockstudio îl stochează și nu îl redă niciodată.
Runtime-ul înregistrează mapările elementelor și aliasurile etichetelor în filtrele PHP, pe care analiza statică nu le poate evalua, așa că analiza le citește din blockstudio.json. scanPhp verifică și etichetele din alte PHP ale proiectului, precum marcajul componentelor din module, fără să raporteze blocuri necunoscute acolo:
{
"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 element se mapează la un nume de bloc sau la reguli testate în ordine: câștigă prima regulă al cărei atribut este prezent pe element, iar un nume simplu de bloc se potrivește întotdeauna. Elementele pe care proiectul nu le mapează își păstrează blocul de bază și nu sunt verificate. Diagnosticările folosesc blockstudio.blockTag.unknown, blockstudio.blockTag.attribute și blockstudio.blockTag.class.
Tipizarea înregistrărilor bazei de date
Db::get() returnează o instanță tipizată pe baza schemei db.php. Structurile înregistrărilor sunt deduse automat.
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
Câmpurile obligatorii acceptă valori nenule. Câmpurile opționale sunt type|null. Un câmp id (int) este întotdeauna prezent. Aceeași tipizare funcționează și cu sintaxa nativă pentru PHP, de tip builder, Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.
Validarea căilor setărilor
Căile Settings::get() sunt verificate în raport cu schema cunoscută a setărilor.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Validarea numelor hookurilor
Numele hookurilor de filtrare și de acțiune Blockstudio sunt validate.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Hookurile dinamice pentru setări, precum blockstudio/settings/tailwind/enabled, sunt întotdeauna permise. Hookurile care nu aparțin blockstudio sunt ignorate.
Validarea schemei
Extensia validează fiecare fișier de schemă Blockstudio din proiect.
block.json:
- Câmpul
namelipsește - Lipsește câmpul
type - Lipsește
idpentru câmpurile cu valori care necesită unul - Tipuri de câmp necunoscute
- Proprietăți ale câmpului neacceptate de tipul respectiv, precum
"translat"în loc de"translate", cu sugestia celei mai apropiate proprietăți cunoscute select/radio/checkboxfărăoptionssaupopulate- ID-uri de câmp duplicate
- Un câmp
tabsîntr-un repetor, direct sau într-un grup fărăid - Declarații
pluginDependenciesinvalide
Câmpurile container, precum group și tabs, precum și referințele la câmpul custom/*, pot omite id dacă doar extind sau încadrează alte câmpuri.
Proprietățile câmpurilor sunt verificate în raport cu proprietățile schemas/block.json declarate pentru fiecare tip de câmp încorporat, precum și cu proprietățile acceptate de toate câmpurile. Proprietățile specifice wrapperului pentru referințele custom/* și tipurile de câmp cu namespace definite în proiect nu intră în această verificare. Validarea existentă a tipurilor de câmp și a referințelor personalizate se aplică în continuare. Identificatorii sunt blockstudio.blockJson.property și blockstudio.fieldJson.property.
Această verificare vizează numele proprietăților, nu doar valorile lor: minimized este validă într-un repeater, dar este semnalată într-un câmp text. Comportamentul pluginului în timpul execuției rămâne neschimbat. Dacă proiectul atașează în mod intenționat propriile metadate la câmpurile încorporate, suprimați doar aceste constatări, fără să dezactivați celelalte verificări ale structurii:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Câmpurile încorporate dintr-un field.json reutilizabil sunt verificate în continuare, chiar și atunci când o referință custom/* are propriile opțiuni wrapper. Fișierele de extensie nu intră în domeniul acestor diagnostice privind numele proprietăților; regulile set specifice extensiilor rămân valabile.
field.json (câmpuri personalizate reutilizabile):
- Lipsește
name attributeslipsește sau este gol- Obiecte de atribute nevalide sau
typede câmp lipsă - Lipsește
idpentru câmpurile de valoare care necesită unul - Tipuri de câmp necunoscute
- Proprietăți pe care tipul câmpului nu le acceptă
- Un câmp
tabsîntr-un repeater, direct sau în interiorul unui grup fărăid - Referințe
custom/*imbricate care lipsesc, sunt ambigue, nevalide sau ciclice
Extensie JSON (extensii de blocuri în extensions/):
- Lipsește
name(blocul țintă) - Lipsește cheia
blockstudio - Lipsește cheia
blockstudio.extend
page.json (pagini bazate pe fișiere):
- Lipsește
title - Lipsește
slug - Valori
postStatusinvalide
db.php:
- Lipsește array-ul
fields - Tipuri de câmp invalide
- Sunt acceptate atât array-urile vechi, cât și
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Metode HTTP invalide
- Valoare
publicincorectă (trebuie să fietrue,falsesau'open') - Sunt acceptate atât array-urile vechi, cât și valorile returnate ca obiecte cu atribute
cron.php:
- Lipsește
schedulepentru sarcinile configurate - Lipsește
callbackpentru sarcinile configurate - Acceptă atât tablouri vechi, cât și valori returnate ca obiecte cu atribute
blockstudio.json:
- Valori booleene prescurtate precum
"tailwind": true(trebuie folosit formatul de obiect imbricat{"enabled": true, "config": ""})
Configurare
În mod implicit, extensia descoperă fișierele Blockstudio din proiectul analizat.
Când proiectul folosește blocuri sau câmpuri reutilizabile dintr-o bibliotecă din afara rădăcinii
proiectului, adăugați calea bibliotecii la blockstudioScanRoots. Calea este
scanată atât pentru definiții block.json, cât și field.json, astfel încât etichetele blocurilor externe
și câmpurile lor personalizate să poată fi validate împreună.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Pentru a ignora fișiere, folosiți configurația standard excludePaths a PHPStan.
Presetări de analiză
Extensia descoperită automat rămâne baza sigură pentru compatibilitate. Blockstudio 7.6 adaugă straturi opționale fără a schimba proiectele existente:
| Presetare | Comportament |
|---|---|
base.neon |
Analiza existentă pentru schemă, șabloane, hook-uri, setări și API. |
theme.neon |
Baza plus rădăcinile temei WordPress, antete de stil, resurse Blockstudio, limitarea selectorilor, valori implicite ale câmpurilor și limite pentru repetatoare. |
extreme-theme.neon |
Tema plus PHPStan max, PHP nesigur, escaparea ieșirii, Tailwind, JavaScript și verificări Interactivity API. |
wordpress-render.neon |
Tema extremă plus o verificare de randare live WordPress furnizată de apelant. |
Instalarea blockstudio/phpstan activează doar extensia de bază. Includeți un strat opțional într-o configurație PHPStan existentă:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths controlează scanerul temei.
Configurația standard excludePaths a PHPStan controlează separat analiza PHP.
Setarea phpstan.excludePaths a comenzii canonice din blockstudio.json
(și opțiunea sa --exclude) configurează ambele straturi. Modelele relative sunt rezolvate
raportat la fiecare rădăcină configurată, astfel încât intrări precum vendor/** limitează analiza PHPStan,
precum și scanarea proiectului de către Blockstudio.
Un model care numește un singur director, precum _dist/** sau node_modules/**,
exclude acel director oriunde apare, nu doar lângă rădăcina temei. Un model
care conține o bară oblică, precum assets/*/docs/**, rămâne ancorat la rădăcină. Resursele de bloc generate se află într-un director _dist din fiecare bloc, așa că forma cu un singur director exclude rezultatul compilat din analiză.
Comanda canonică
Pachetul instalează vendor/bin/blockstudio-phpstan ca executabil de analiză.
Rulează presetarea base dacă proiectul nu selectează alta, așadar instalarea pachetului nu activează singură straturile pentru temă sau temă extremă:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Presetările includ ele însele extensia. Nu adăugați phpstan/extension-installer
într-un proiect care rulează comanda canonică:
cu instalatorul prezent, extension.neon este încărcat de două ori, iar PHPStan se oprește
cu mesajul „This file is included multiple times” înainte de a analiza ceva.
În mod implicit, comanda setează PHPStan la o limită de memorie 1G, astfel încât proiectele WordPress gestionate de Composer să nu moștenească plafonul obișnuit 128M CLI. Transmiteți o opțiune PHPStan explicită după -- pentru a o suprascrie, de exemplu -- --memory-limit=512M --no-progress.
Adoptarea analizei într-un proiect existent
Un proiect care nu a fost analizat niciodată va raporta de obicei probleme la prima rulare. În loc să reduceți nivelul presetării, generați o bază de referință PHPStan și indicați-i lui phpstan.configuration o configurație de proiect care o include. Codul nou va trebui apoi să respecte presetarea completă, iar problemele deja înregistrate nu vor încurca:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Păstrați linia level pentru presetările base și theme. Comanda canonică setează nivelul max pentru acestea doar când nu este inclusă nicio configurație de proiect, iar fără un nivel PHPStan se oprește cu mesajul „No rules detected”. Presetarea extreme-theme setează singură nivelul max.
Căile relative sunt rezolvate pornind de la blockstudio.json. Atât comanda canonică, cât și hook-ul de commit gestionat detectează fișierul, astfel încât hook-ul să blocheze problemele noi fără a cere rezolvarea mai întâi a celor restante.
Păstrați valorile implicite ale comenzilor pentru întregul proiect în blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Rădăcinile relative sunt rezolvate pornind de la fișierul care le declară. Valorile explicite CLI înlocuiesc valorile corespunzătoare JSON. Transmiteți --blockstudio-json path/to/project.json pentru o sursă de configurare alternativă. Configurațiile JSON malformate, cheile phpstan nesuportate, valorile nevalide și lipsa unei surse explicite duc în mod determinist la codul de ieșire 2.
Selectați altă presetare, includeți o configurație de proiect, adăugați rădăcini și excluderi repetabile sau solicitați-i lui PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Wrapperul compune configurația în directorul temporar al sistemului și o șterge la ieșire. Nu scrie configurații generate, baze de referință, hook-uri sau cache-uri în proiectul analizat. Apelanții pot configura în continuare explicit memoria cache obișnuită a PHPStan.
Contractul codurilor de ieșire este:
0dacă analiza trece1dacă PHPStan raportează diagnostice2pentru utilizare, configurare sau execuție nevalidă a procesului
Hook de commit gestionat
Pentru a transforma analiza temei extreme într-o verificare la commit pentru depozit, activați hook-ul gestionat de Blockstudio în blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Sincronizați-l după instalarea dependențelor sau schimbarea setării:
vendor/bin/blockstudio-githooks sync
Comanda scrie hook-ul pre-commit generat și înregistrarea de proprietate în directorul comun al Git, setează core.hooksPath la directorul hook-ului gestionat și leagă în siguranță hook-ul pre-commit configurat anterior. Sincronizările repetate reîmprospătează doar fișierul generat, astfel încât actualizările pachetului sunt idempotente.
Setați commit la false, eliminați-l sau eliminați blockstudio.json, apoi rulați sync pentru a restaura calea hook-ului înregistrată și a șterge doar fișierele deținute de Blockstudio. Puteți rula și:
vendor/bin/blockstudio-githooks remove
Fișierele deținute de utilizator nu sunt niciodată suprascrise sau șterse. Dacă cineva schimbă core.hooksPath după activarea Blockstudio, eliminarea păstrează noua setare. Hook-ul generat acceptă clone Git asociate și căi care conțin spații, rezolvând depozitul activ și rădăcina proiectului la momentul commitului. Rulează comanda canonică din acea rădăcină, astfel încât același obiect phpstan să controleze atât rulările interactive, cât și commiturile, fără argumente generate duplicate.
Hook-ul rulează doar vendor/bin/blockstudio-phpstan. Blockstudio nu rulează un formator, iar hook-ul nu rescrie niciodată fișierele proiectului. Dependențele lipsă și eșecurile analizei blochează commitul cu o eroare clară și utilă.
Randare live WordPress
Stratul live este intenționat explicit. Apelantul deține mediul WordPress și furnizează un tablou argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Comanda rulează fără shell și trebuie să afișeze un singur obiect JSON:
{"ok":true}
O verificare poate raporta o problemă specifică:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Ieșirile non-zero, expirările de timp, valorile JSON malformate și ok: false produc
blockstudio.wordpress.render.
blockstudio.javascript.domContract semnalează un selector de atribut [data-*] pe care un script îl transmite către querySelector(), querySelectorAll(), closest() sau matches(), atunci când niciunul dintre fragmentele de markup analizate nu conține acel atribut. Markupul cuprinde fiecare fișier PHP, Twig, Blade și HTML, precum și fiecare componentă React .tsx și .jsx din rădăcinile analizate, cu excepția căilor excluse. Componentele sunt analizate: numele atributelor JSX sunt luate în considerare, la fel și cheile text de tip string ale obiectelor literale. Astfel, un obiect de atribute extins într-un element satisface selectorul, în timp ce numele claselor și alte valori ale atributelor nu îl satisfac.
Verificările Interactivity API citesc aceleași componente React. Un namespace data-wp-interactive pe un element JSX este considerat o referință de șablon pentru blockstudio.interactivity.orphan, iar directivele data-wp-* din interiorul acestuia se rezolvă în raport cu cel mai apropiat namespace încadrant sau cu un prefix namespace:: din valoare. Directivele cu o valoare statică de tip string, scrise ca atribut JSX sau ca cheie de tip string a unui obiect de atribute, trebuie să indice gestionari și căi existente în store (blockstudio.interactivity.handler, blockstudio.interactivity.binding), iar codul store-ului nu trebuie să modifice atributele și clasele la care sunt asociate (blockstudio.interactivity.derivedState). React escapează valorile atributelor, așa că data-wp-context dintr-o componentă nu este semnalată, iar valorile dinamice nu sunt verificate. Namespace-urile din bsui/ aparțin blocurilor UI incluse în pachet, ale căror store-uri sunt livrate cu Blockstudio în afara rădăcinilor analizate, deci nu sunt niciodată orfane.
Identificatori de diagnostic
Noile diagnostice ale presetărilor păstrează ID-uri blockstudio.* stabile:
- Structura temei:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Resurse și câmpuri:
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 - Interactivitate:
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
Performanță
Scanerul acceptă directoare materializate obișnuite, elimină duplicatele dintre rădăcini, omite arborii dependențelor, compilărilor și cache-ului, memorează citirile fișierelor în cache și sortează determinist diagnosticele. Păstrați rădăcinile restrânse, excludeți arborii de teste și cei generați și setați o limită de fișiere pentru depozitele mari. JavaScript și Tailwind pot fi dezactivate independent. Randarea live nu rulează decât dacă este selectată presetarea corespunzătoare.
Diagnosticele pentru temă, JavaScript și Tailwind sunt raportate prin cache-ul de rezultate al PHPStan. După schimbarea doar a unui block.json sau a unui script, un cache cald poate raporta rezultatul anterior. Transmiteți --debug după -- pentru a ocoli cache-ul la verificarea acestor schimbări.
Contractul proiectului pentru agenții de programare
Pachetul instalează un al treilea executabil, vendor/bin/blockstudio-agents. Acesta
scrie un AGENTS.md care descrie proiectul în care rulează, informațiile de care un agent de programare are nevoie înainte să modifice ceva: ce creează proiectul, ce funcționalități Blockstudio sunt activate, ce va respinge analiza și ce comenzi se aplică.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Nimic din rezultat nu este un șablon fix. Fiecare linie provine din una dintre cele trei surse:
- Fișierele proprii ale proiectului. O temă cu un antet
style.css, blocuri și pagini bazate pe fișiere produce un document diferit de cel al unui plugin care doar înregistrează blocuri. Numărul, directoarele, spațiile de nume ale blocurilor și limbajele șabloanelor sunt cele găsite efectiv de scaner, folosind aceleași rădăcini și excluderi ca analiza. blockstudio.json. Sunt descrise doar funcționalitățile activate, împreună cu valorile configurate: prefixele etichetelor blocurilor și spațiile de nume prin care sunt rezolvate, Tailwind, pachetul UI, resetarea resurselor editorului, calea cache-ului, profilul de performanță, pre-randarea statică și căile dinamice ale acesteia, valorile implicite ale temei, Content Sync și hook-ul de commit.phpstan.presetselectată. Secțiunea despre corectitudine este citită din fișierele presetării, strat cu strat, și enumeră exact regulile înregistrate de presetare. Labasedescrie regulile pentru schemă, șabloane, hook-uri și setări. Laextreme-themedescrie și regulile pentru structura temei, indicatorii stricti PHPStan, PHP nesigur, escaparea ieșirii, Tailwind și JavaScript. Când presetarea primește o regulă, documentul generat se actualizează și el.
Secțiunea despre comenzi urmează același principiu. wp bs prerender status
apare când este activată pre-randarea statică, vendor/bin/blockstudio-githooks sync când este setat githooks.commit, iar wp bs db schemas când proiectul are efectiv un db.php.
| Opțiune | Comportament |
|---|---|
--root <path> |
Rădăcina proiectului (implicit: directorul curent) |
--config <path> |
Calea blockstudio.json (implicit: <root>/blockstudio.json) |
--output <path> |
Calea contractului (implicit: <root>/AGENTS.md) |
--stdout |
Afișează contractul în loc să îl scrie |
--check |
Iese cu 1 dacă contractul de pe disc nu este actualizat |
--force |
Înlocuiește un fișier pe care Blockstudio nu îl deține |
--check transformă contractul într-o verificare CI, la fel cum hook-ul de commit transformă analiza într-una:
vendor/bin/blockstudio-agents --check
Proprietate
Fișierul generat conține același tip de marcaj ca hook-ul de commit gestionat,
și se aplică aceeași regulă: Blockstudio nu înlocuiește niciodată un fișier pe care nu l-a scris.
Un AGENTS.md existent înaintea comenzii sau scris manual de un autor este
refuzat cu codul de ieșire 2 și lăsat neatins până când se transmite --force.
Regenerarea este sigură. Fișierul se încheie cu o secțiune de note, iar octeții dintre marcajele acesteia sunt păstrați la fiecare regenerare:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Codurile de ieșire sunt 0 când contractul este scris, actualizat sau afișat, 1 când --check găsește un contract învechit și 2 pentru erori de utilizare, configurare sau sistem de fișiere.
Formele tipurilor de câmpuri
Extensia asociază fiecărui tip de câmp Blockstudio un tip concret PHP:
| Tipul câmpului | Tipul PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (simplu) |
string|int |
select, checkbox (multiplu) |
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 (simplu) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (multiplu) |
list<array{id: int, url: string, ...}> |
group |
Grupurile denumite folosesc prefixe underscore; grupurile anonime sunt aplatizate în domeniul părinte |
repeater |
list<array{...child fields...}> |
tabs |
Aplatizat în domeniul părinte |
Stub-uri API
Extensia include stub-uri pentru întregul Blockstudio public 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()
Acestea oferă completarea automată și verificarea tipurilor fără a avea nevoie de codul sursă al pluginului Blockstudio pe calculator.
Cerințe
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(recomandat pentru descoperire automată)
Pachetul instalează automat furnizorul său de compatibilitate BC Math. Prin urmare, ext-bcmath nativ este opțional, inclusiv pentru temele nou generate care activează verificările JavaScript prin presetarea pentru temă sau cea extremă.