PHPStan
Plėtinys blockstudio/phpstan suteikia statinės analizės galimybes Blockstudio projektams. Jis analizės metu tikrina blokų šablonus, schemų failus, nustatymų kelius ir kabliukų pavadinimus, taip aptikdamas klaidas dar prieš joms pasiekiant vykdymo aplinką.
Diegimas
composer require --dev blockstudio/phpstan
7.7 versijos šablonų tipizavimui ir išplėstiniams blokų žymų patikrinimams reikia blockstudio/phpstan 0.1.9 ar naujesnės versijos ir PHPStan 2.1.47 ar naujesnės versijos. Paketą atnaujinkite atskirai nuo papildinio:
composer require --dev blockstudio/phpstan:^0.1.9
Plėtinys aptinkamas automatiškai per PHPStan plėtinių diegimo programą. Nereikia jokios rankinės konfigūracijos.
Ką tikrina
Prieiga prie šablono laukų
Kai failas PHP yra šalia block.json, plėtinys tikrina kiekvieną prieigą $a['key'] pagal deklaruotus bloko atributus.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Plėtinys žino, kad Blockstudio apibrėžia $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview ir salos kintamuosius prieš įtraukdamas šabloną, todėl tiesioginės prieigos, tokios kaip $a['title'], nelaikomos galimai neapibrėžtomis, o $a tipas nustatomas pagal šalia šablono esančią block.json. Ši struktūra išlieka siaurinant tipus, todėl $a['label'] ?? '', isset( $a['cta']['target'] ) ir $a['cta']['title'] !== null išlaiko deklaruotus laukų tipus; jei šablonas priskiria reikšmę pačiam $a, jam priskirtas tipas išlieka. Nedėkite /** @var array<string, mixed> $a */ dokumentacijos bloko: jis pakeičia šią struktūrą atviru masyvu.
Laukų raktams taikomos Blockstudio vykdymo aplinkos išlyginimo taisyklės. tabs ir anoniminiai group konteineriai be id skirti tik pateikimui, todėl jų antriniai laukai lieka pirminėje srityje. Pavadinta grupė prie antrinių laukų raktų prideda grupės ID:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Pakartotinai naudojami pasirinktiniai laukai
Prieš tikrinant šablonų raktus ir masyvų struktūras, išplečiamos failuose apibrėžtos custom/* nuorodos. Plėtinys nuskaito atitinkamą field.json ir taiko tas pačias idStructure, overrides, įdėtinių nuorodų, grupių, skirtukų ir kartotuvų taisykles kaip 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" }
}
}
]
}
}
Gauti šablonų raktai yra title ir hero_description. Jie atpažįstami srityse PHP, Twig, Blade, blokų žymose ir nustatomose atributų struktūrose.
Trūkstant, esant dviprasmiškam, netinkamam ar cikliniam failuose apibrėžtam aprašui, pateikiama konkreti blockstudio.customField.* klaida. To bloko priklausomų raktų patikros praleidžiamos, kad vienas neišspręstas aprašas nesukeltų papildomos klaidų dėl nežinomų laukų bangos.
Statinė analizė negali nustatyti aprašų, registruojamų tik vykdymo metu per filtrą blockstudio/fields PHP. Jei laukui reikia statiškai tikrinamų šablonų raktų, naudokite aprašą field.json.
Prieiga prie Twig šablonų
Twig šablonai nuskaitomi automatiškai. Anotacijų nereikia.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Prieiga prie Blade šablonų
Blade šablonai nuskaitomi tokiu pačiu būdu.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Blokų žymų tikrinimas
Blokų žymos tikrinamos ten, kur Blockstudio jas nuskaito: <bs:> ir <block> žymose, blockTags.prefixes sukonfigūruotose prefiksų žymose (pavyzdžiui, <acme-card>, nustatomose pagal vardų sričių tvarką, kaip ir vykdymo aplinkoje) ir alternatyviose žymose; šablonuose PHP, Twig bei Blade ir puslapių išdėstymuose. Taip pat tikrinami puslapių šaltiniai, esantys žemiau pages/ (index.php, index.html, index.twig, index.blade.php), įskaitant HTML elementus, kuriuos projektas susieja su blokais. Kai įjungta ui.enabled, atpažįstami ir komplekte esantys UI blokai.
<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) -->
Atributas priimamas, jei blokas jį deklaruoja kaip lauką (įskaitant pasirinktinius laukus ir laukus, kuriuos bloko tipo laukas perduoda per savo idStructure) arba jei Blockstudio perduoda jį pagrindiniam bloko elementui: data-*, aria-*, id, style, role, title, lang, dir, hidden ir tabindex. Šablonuose perduodami visi html-* atributai; puslapių šaltiniuose html- prefiksas nurodo tik vieną iš perduodamų atributų. Pranešama apie visus kitus atributus, ypač nedeklaruotą class, nes Blockstudio jį išsaugo, bet niekada neatvaizduoja.
Vykdymo aplinka registruoja elementų susiejimus ir žymų alternatyvas filtruose PHP, kurių statinė analizė negali įvertinti, todėl analizė juos nuskaito iš blockstudio.json. scanPhp taip pat tikrina žymas kituose projekto PHP failuose, pavyzdžiui, komponentų žymėjime moduliuose, tačiau nepraneša apie ten esančius nežinomus blokus:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Elementas susiejamas su bloko pavadinimu arba taisyklių seka, tikrinama eilės tvarka: pritaikoma pirma taisyklė, kurios atributą turi elementas, o paprastas bloko pavadinimas visada atitinka. Nesusieti projekto elementai išlaiko pagrindinį bloką ir nėra tikrinami. Diagnostikoje naudojami blockstudio.blockTag.unknown, blockstudio.blockTag.attribute ir blockstudio.blockTag.class.
Duomenų bazės įrašų tipizavimas
Db::get() pateikia tipizuotą egzempliorių pagal db.php schemą. Įrašų struktūros nustatomos automatiškai.
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
Privalomi laukai nėra nuliniai. Pasirinktiniai laukai yra type|null. Laukas id (int) visada pateikiamas. Toks pats tipizavimas taikomas PHP savitajai Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field kūrimo sintaksei.
Nustatymų kelių tikrinimas
Settings::get() keliai tikrinami pagal žinomą nustatymų schemą.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Kabliukų pavadinimų tikrinimas
Tikrinami Blockstudio filtrų ir veiksmų kabliukų pavadinimai.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dinaminiai nustatymų kabliukai, tokie kaip blockstudio/settings/tailwind/enabled, visada leidžiami. Ne blockstudio kabliukai ignoruojami.
Schemos tikrinimas
Plėtinys tikrina kiekvieną projekto Blockstudio schemos failą.
block.json:
- Trūksta
namelauko - Trūksta lauko
type - Trūksta
idlaukams, kuriems jis reikalingas - Nežinomi laukų tipai
- Lauko savybės, kurių laukų tipas nepriima, pavyzdžiui,
"translat"vietoj"translate"; pasiūloma artimiausia žinoma savybė select/radio/checkboxbeoptionsarbapopulate- Pasikartojantys laukų ID
tabslaukas kartotuvo viduje – tiesiogiai arba grupėje beid- Netinkamos
pluginDependenciesdeklaracijos
Konteinerių laukuose, pavyzdžiui, group ir tabs, taip pat custom/* laukų nuorodose, galima nenurodyti id, jei jos tik išplečia ar apgaubia kitus laukus.
Laukų savybės tikrinamos pagal savybes, kurias kiekvienam integruotam lauko tipui deklaruoja schemas/block.json, ir savybes, kurias priima visi laukai. custom/* nuorodoms skirtos savybės ir projekte apibrėžti vardų srities lauko tipai į šį tikrinimą neįtraukiami. Esami lauko tipų ir pasirinktinių nuorodų tikrinimai lieka galioti. Identifikatoriai: blockstudio.blockJson.property ir blockstudio.fieldJson.property.
Tikrinami savybių pavadinimai, o ne vien jų reikšmės: minimized galioja kartotiniam laukui, bet apie jį pranešama teksto lauke. Įskiepio veikimas vykdymo metu nesikeičia. Jei projekte prie integruotų laukų sąmoningai pridedami savi metaduomenys, slopinkite tik šiuos radinius, neišjungdami kitų struktūros patikrų:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Integruoti laukai daugkartinio naudojimo field.json viduje vis tiek tikrinami, net jei custom/* nuoroda turi savų apvalkalo parinkčių. Plėtinio failai nepatenka į šios savybių pavadinimų diagnostikos apimtį; plėtiniui būdingos set taisyklės lieka galiojančios.
field.json (pakartotinai naudojami pasirinktiniai laukai):
- Trūksta
name - Trūksta arba tuščias
attributes - Netinkami atributų objektai arba trūksta lauko
type - Trūksta
idreikšmės laukams, kuriems jis būtinas - Nežinomi laukų tipai
- Lauko savybės, kurių lauko tipas nepriima
tabslaukas kartotiniame lauke tiesiogiai arba grupėje beid- Trūksta įdėtinių
custom/*nuorodų arba jos dviprasmės, netinkamos ar ciklinės
Plėtinys JSON (blokų plėtiniai extensions/):
- Trūksta
name(paskirties bloko) - Trūksta rakto
blockstudio - Trūksta rakto
blockstudio.extend
page.json (failais pagrįsti puslapiai):
- Trūksta
title - Trūksta
slug - Netinkamos
postStatusreikšmės
db.php:
- Trūksta masyvo
fields - Netinkami laukų tipai
- Palaikomi ir senieji masyvai, ir
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Netinkami HTTP metodai
- Neteisinga
publicreikšmė (turi būtitrue,falsearba'open') - Palaikomi ir senieji masyvai, ir atributais pažymėtų objektų grąžinamos reikšmės
cron.php:
- Trūksta
schedulesukonfigūruotose užduotyse - Trūksta
callbacksukonfigūruotose užduotyse - Palaikomi ir senieji masyvai, ir grąžinami objektai su atributais
blockstudio.json:
- Trumpieji loginiai įrašai, pvz.,
"tailwind": true(būtina naudoti įdėtinio objekto formatą{"enabled": true, "config": ""})
Konfigūracija
Plėtinys pagal numatytuosius nustatymus aptinka Blockstudio failus analizuojamame projekte.
Jei projekte naudojami blokai arba pakartotinai naudojami laukai iš bibliotekos, esančios už
projekto šakninio katalogo ribų, pridėkite bibliotekos kelią prie blockstudioScanRoots. Kelias
skenuojamas ieškant ir block.json, ir field.json apibrėžčių, todėl išorinių blokų
gairės ir jų tinkinti laukai gali būti tikrinami kartu.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Norėdami ignoruoti failus, naudokite standartinę excludePaths konfigūraciją, skirtą PHPStan.
Analizės išankstiniai nustatymai
Automatiškai aptinkamas plėtinys išlieka suderinamumui saugiu pagrindu. Blockstudio 7.6 prideda pasirenkamus sluoksnius nekeisdama esamų projektų:
| Išankstinis nustatymas | Veikimas |
|---|---|
base.neon |
Esamos schemos, šablono, kabliukų, nustatymų ir API analizė. |
theme.neon |
Pagrindas ir WordPress temų šakniniai katalogai, stilių antraštės, Blockstudio ištekliai, selektorių aprėpties apribojimas, laukų numatytosios reikšmės ir kartotuvo ribos. |
extreme-theme.neon |
Tema ir PHPStan max, nesaugus PHP, išvesties ekranavimas, Tailwind, JavaScript ir Interactivity API patikros. |
wordpress-render.neon |
Ekstremali tema ir skambintojo pateiktas tiesioginis WordPress atvaizdavimo patikrinimas. |
Įdiegus blockstudio/phpstan įjungiamas tik pagrindinis plėtinys. Įtraukite pasirenkamą
sluoksnį į esamą PHPStan konfigūraciją:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths valdo temų skaitytuvą.
Standartinis excludePaths nustatymas, skirtas PHPStan, atskirai valdo PHP analizę.
Kanoninės komandos nustatymas phpstan.excludePaths faile blockstudio.json
(ir jos parinktis --exclude) konfigūruoja abu sluoksnius. Santykiniai šablonai sprendžiami pagal kiekvieną sukonfigūruotą šakninį katalogą, todėl tokie įrašai kaip vendor/** apriboja PHPStan analizę ir Blockstudio projekto skenavimą.
Vieną katalogą nurodantis šablonas, pvz., _dist/** arba node_modules/**,
neįtraukia to katalogo, kad ir kur jis būtų, o ne tik šalia temos šakninio katalogo. Šablonas su pasviruoju brūkšniu, pvz., assets/*/docs/**, išlieka susietas su šakniniu katalogu. Sugeneruoti blokų ištekliai laikomi kiekvieno bloko _dist kataloge, todėl kompiliuotą išvestį nuo analizės apsaugo vieno katalogo forma.
Kanoninė komanda
Paketas įdiegia vendor/bin/blockstudio-phpstan kaip analizės vykdomąjį failą. Jei projektas
nepasirenka kito nustatymo, vykdoma base išankstinė nuostata, todėl vien paketo įdiegimas savaime neįjungia temos ar ekstremalios temos sluoksnių:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Patys išankstiniai nustatymai įtraukia plėtinį. Nepridėkite
phpstan/extension-installer prie projekto, kuriame vykdoma kanoninė komanda:
įdiegus paketą, extension.neon įkeliamas du kartus, o PHPStan sustoja
su pranešimu „Šis failas įtrauktas kelis kartus“ dar nepradėjęs analizės.
Pagal numatytuosius nustatymus komanda nustato PHPStan į 1G atminties limitą, kad Composer valdomi
WordPress projektai nepaveldėtų įprastos 128M CLI ribos. Norėdami jį pakeisti, po -- perduokite aiškią parinktį PHPStan, pvz.,
-- --memory-limit=512M --no-progress.
Analizės pritaikymas esamame projekte
Pirmą kartą analizuojant projektą paprastai aptinkama problemų. Užuot sumažinę išankstinio nustatymo griežtumą, sukurkite PHPStan bazinį failą ir nurodykite phpstan.configuration projekto konfigūraciją, kurioje jis įtrauktas. Naujasis kodas ir toliau tikrinamas pagal visą išankstinį nustatymą, o užfiksuotos problemos netrukdo:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Palikite eilutę level naudodami base ir theme išankstinius nustatymus. Kanoninė komanda jiems nustato tik max lygį, kai neįtraukta jokia projekto konfigūracija; jei lygis nenustatytas, PHPStan sustoja su pranešimu „Taisyklių nerasta“. extreme-theme išankstinis nustatymas pats nustato max lygį.
Santykiniai keliai sprendžiami pagal blockstudio.json. Kanoninė komanda ir
valdomas pakeitimų patvirtinimo kabliukas aptinka šį failą, todėl kabliukas blokuoja naujas problemas, bet pirmiausia nereikia pašalinti visų senų.
Visos projektui skirtos numatytosios komandų reikšmės turi būti faile blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Santykiniai šakniniai katalogai nustatomi pagal juos deklaruojantį failą. Aiškios CLI reikšmės pakeičia atitinkamas JSON reikšmes. Norėdami nurodyti kitą konfigūracijos šaltinį, perduokite --blockstudio-json path/to/project.json. Netaisyklingas JSON, nepalaikomi phpstan raktai, netinkamos reikšmės ir nurodyto šaltinio nebuvimas visada pateikia klaidą su išėjimo kodu 2.
Pasirinkite kitą išankstinį nustatymą, įtraukite projekto konfigūraciją, pridėkite kartotinius šakninius katalogus ir išimtis arba paprašykite PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Apvalkalas sudaro konfigūraciją laikinojoje sistemos direktorijoje ir ištrina ją baigęs darbą. Jis niekada neįrašo sugeneruotos konfigūracijos, bazinių failų, kabliukų ar podėlių į analizuojamą projektą. Vis dėlto skambintojai gali aiškiai sukonfigūruoti įprastą PHPStan podėlį.
Išėjimo kodai:
0, jei analizė sėkminga1, jei PHPStan pateikia diagnostikos pranešimų2, jei netinkamai naudojama, sukonfigūruota arba vykdomas procesas
Valdomas pateikimo pakeitimų kabliukas
Kad ekstremalios temos analizė taptų saugyklos pakeitimų patvirtinimo patikra, įjunkite Blockstudio valdomą kabliuką faile blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Sinchronizuokite jį įdiegę priklausomybes arba pakeitę nustatymą:
vendor/bin/blockstudio-githooks sync
Komanda įrašo sugeneruotą išankstinio patvirtinimo kabliuką ir nuosavybės įrašą į bendrą Git katalogą, nustato core.hooksPath į valdomo kabliuko katalogą ir saugiai susieja anksčiau sukonfigūruotą išankstinio patvirtinimo kabliuką. Kartotinė sinchronizacija atnaujina tik sugeneruotą failą, todėl paketo naujinimus galima taikyti pakartotinai be šalutinių pakeitimų.
Nustatykite commit į false, pašalinkite jį arba pašalinkite blockstudio.json, tada paleiskite sync, kad būtų atkurtas įrašytas kabliuko kelias ir ištrinti tik Blockstudio priklausantys failai. Taip pat galite paleisti:
vendor/bin/blockstudio-githooks remove
Naudotojams priklausantys failai niekada neperrašomi ir neištrinami. Jei kas nors pakeičia core.hooksPath po to, kai įjungiamas Blockstudio, šalinant išsaugomas naujesnis nustatymas. Sugeneruotas kabliukas palaiko susietus Git darbinius katalogus ir tarpus keliuose, nes pakeitimų patvirtinimo metu nustato aktyvią saugyklą ir projekto šakninį katalogą. Jis vykdo kanoninę komandą iš to šakninio katalogo, todėl tas pats phpstan objektas valdo interaktyvius paleidimus ir pakeitimų patvirtinimus, o sugeneruotų argumentų dubliuoti nereikia.
Kabliukas vykdo tik vendor/bin/blockstudio-phpstan. Blockstudio neformatuoja kodo ir kabliukas niekada neperrašo projekto failų. Trūkstamos priklausomybės ir analizės klaidos blokuoja pakeitimų patvirtinimą, pateikdamos aiškų klaidos pranešimą.
Tiesioginis WordPress atvaizdavimas
Tiesioginis sluoksnis įjungiamas aiškiai. Skambintojas valdo WordPress aplinką ir pateikia argv masyvą:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Komanda vykdoma be apvalkalo ir turi išvesti vieną JSON objektą:
{"ok":true}
Patikra gali pateikti konkrečią klaidą:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Nulinio kodo neatitinkantys išėjimai, skirtojo laiko pabaiga, netaisyklingas JSON ir ok: false pateikia blockstudio.wordpress.render.
blockstudio.javascript.domContract praneša apie [data-*] atributo selektorių, kurį scenarijus perduoda querySelector(), querySelectorAll(), closest() arba matches(), kai nė viename analizuojamame žymėjime šio atributo nėra. Žymėjimą sudaro visi PHP, Twig, Blade ir HTML failai bei visi React .tsx ir .jsx komponentai analizuojamose šakninėse direktorijose, išskyrus atmestus kelius. Komponentai išskaidomi: JSX atributo pavadinimai įskaitomi, kaip ir objektų literatų eilučių raktai, todėl elementui pritaikytas atributų objektas atitinka selektorių, o klasių pavadinimai ir kitos atributų reikšmės – ne.
Interaktyvumo API patikros skaito tuos pačius React komponentus. JSX elemente esanti data-wp-interactive vardų sritis laikoma šablono nuoroda, skirta blockstudio.interactivity.orphan, o joje esančios data-wp-* direktyvos susiejamos su artimiausia išorine vardų sritimi arba su namespace:: prefiksu reikšmėje. Direktyvos su statine eilutės reikšme, nurodytos kaip JSX atributas arba kaip atributų objekto eilutės raktas, turi nurodyti esamas saugyklos apdorojimo funkcijas ir kelius (blockstudio.interactivity.handler, blockstudio.interactivity.binding), o saugyklos kodas negali keisti atributų ir klasių, su kuriomis jos susietos (blockstudio.interactivity.derivedState). React išvengia atributų reikšmių, todėl apie data-wp-context komponente nepranešama, o dinaminės reikšmės netikrinamos. Vardų sritys po bsui/ priklauso susietiems UI blokams, kurių saugyklos pateikiamos kartu su Blockstudio už analizuojamų šakninių direktorijų ribų, todėl jos niekada nelaikomos našlaitėmis.
Diagnostikos identifikatoriai
Naujos išankstinių nustatymų diagnostikos išlaiko stabilius blockstudio.* ID:
- Temos struktūra:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Ištekliai ir laukai:
blockstudio.theme.asset.manualEnqueue,blockstudio.theme.asset.selectorScope,blockstudio.theme.asset.missing,blockstudio.field.default,blockstudio.field.repeaterBounds - PHP:
blockstudio.php.forbiddenFunction,blockstudio.wordpress.rawDatabaseWrite,blockstudio.output.unescaped - Tailwind:
blockstudio.tailwind.compilerMissing,blockstudio.tailwind.compile,blockstudio.tailwind.unknownUtility,blockstudio.tailwind.semanticToken - JavaScript:
blockstudio.javascript.syntax,blockstudio.javascript.debugOutput,blockstudio.javascript.bannedApi,blockstudio.javascript.leakedGlobal,blockstudio.javascript.importSpecifier,blockstudio.javascript.rootGuard,blockstudio.javascript.initShape,blockstudio.javascript.domContract,blockstudio.javascript.listenerCleanup,blockstudio.javascript.reducedMotion - Interactivity:
blockstudio.interactivity.import,blockstudio.interactivity.moduleImport,blockstudio.interactivity.namespace,blockstudio.interactivity.scopedDom,blockstudio.interactivity.derivedState,blockstudio.interactivity.handler,blockstudio.interactivity.binding,blockstudio.interactivity.context,blockstudio.interactivity.orphan
Našumas
Skaitytuvas priima įprastus katalogus, pašalina pasikartojančius šakninius katalogus, praleidžia priklausomybių, kūrimo ir podėlių katalogų medžius, podėliuoja failų turinį atmintyje ir nuosekliai rūšiuoja diagnostikos pranešimus. Rinkitės siauras šaknines vietas, neįtraukite testinių ir sugeneruotų katalogų, o didelėse saugyklose nustatykite failų limitą. JavaScript ir Tailwind galima išjungti atskirai. Tiesioginis atvaizdavimas vykdomas tik pasirinkus atitinkamą išankstinį nustatymą.
Temos, JavaScript ir Tailwind diagnostikos pateikiamos per PHPStan rezultatų podėlį. Pakeitus tik block.json arba skriptą, podėlyje gali būti pateiktas ankstesnis rezultatas. Norėdami apeiti podėlį ir patikrinti tokius pakeitimus, po -- perduokite --debug.
Projektui taikomos taisyklės programavimo agentams
Paketas įdiegia trečią vykdomąjį failą – vendor/bin/blockstudio-agents. Jis
sugeneruoja AGENTS.md, kuriame aprašomas projektas, kuriame veikia. Tokią informaciją kodavimo agentui reikia žinoti prieš keičiant bet ką: ką kuria projektas, kurios Blockstudio funkcijos įjungtos, ką analizė atmes ir kurios komandos taikomos.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Išvestis nėra sudaryta iš nekintamo šablono. Kiekviena eilutė gaunama iš vieno iš trijų šaltinių:
- Paties projekto failai. Tema su
style.cssantrašte, blokais ir iš failų sudarytais puslapiais sukuria kitokį dokumentą nei papildinys, registruojantis tik blokus. Skaičiai, katalogai, blokų vardų sritys ir šablonų kalbos atspindi tai, ką iš tikrųjų aptiko skaitytuvas, naudodamas tuos pačius šakninius katalogus ir išimtis kaip analizė. blockstudio.json. Aprašomos tik įjungtos funkcijos ir jų sukonfigūruotos reikšmės: blokų gairių priešdėliai ir vardų sritys, per kurias jos sprendžiamos, Tailwind, susietas UI, redaktoriaus išteklių nustatymas iš naujo, podėlio kelias, našumo profilis, statinis išankstinis atvaizdavimas ir jo dinaminiai keliai, numatytieji temos nustatymai, Content Sync ir pakeitimų patvirtinimo kabliukas.- Pasirinktas
phpstan.preset. Teisingumo skyrius skaitomas iš pačių išankstinių nustatymų failų, sluoksnis po sluoksnio, todėl jame išvardytos tiksliai tos taisyklės, kurias registruoja tas nustatymas.baseaprašomos schemos, šablono, kabliukų ir nustatymų taisyklės.extreme-themetaip pat aprašomos temos struktūros taisyklės, griežtos PHPStan vėliavėlės, nesaugus PHP, išvesties ekranavimas, Tailwind ir JavaScript. Kartu su nauja taisykle atnaujinamas ir sugeneruotas dokumentas.
Komandų skyrius sudaromas pagal tą patį principą. wp bs prerender status rodomas įjungus statinį išankstinį atvaizdavimą, vendor/bin/blockstudio-githooks sync – nustačius githooks.commit, o wp bs db schemas – jei projekte iš tiesų yra db.php.
| Parinktis | Veikimas |
|---|---|
--root <path> |
Projekto šakninis katalogas (numatytasis: dabartinis katalogas) |
--config <path> |
blockstudio.json kelias (numatytasis: <root>/blockstudio.json) |
--output <path> |
Taisyklių rinkinio kelias (numatytasis: <root>/AGENTS.md) |
--stdout |
Išveda taisyklių rinkinį jo neįrašydama |
--check |
Grąžina išėjimo kodą 1, jei diske esantis taisyklių rinkinys pasenęs |
--force |
Pakeičia failą, kurio nevaldo Blockstudio |
--check paverčia taisyklių rinkinį CI patikra, kaip pakeitimų patvirtinimo kabliukas paverčia tokia patikra analizę:
vendor/bin/blockstudio-agents --check
Nuosavybė
Sugeneruotame faile įrašoma tokio pat tipo žyma kaip ir valdomame pakeitimų patvirtinimo kabliuke, todėl taikoma ta pati taisyklė: Blockstudio niekada nepakeičia failo, kurio pati nesukūrė.
Jei AGENTS.md buvo sukurtas prieš komandą arba rankiniu būdu autoriaus, jis atmetamas su išėjimo kodu 2 ir paliekamas nepakeistas, kol nepateikiama --force.
Atkurti failą saugu. Jis baigiasi pastabų sritimi, o baitai tarp jos žymų išsaugomi po kiekvieno generavimo:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Kai taisyklių rinkinys įrašomas, yra aktualus arba išvedamas, grąžinamas išėjimo kodas 0; kai --check aptinka pasenusį taisyklių rinkinį – 1; naudojimo, konfigūracijos ar failų sistemos klaidų atveju – 2.
Laukų tipų formos
Plėtinys kiekvieną Blockstudio lauko tipą susieja su konkrečiu PHP tipu:
| Lauko tipas | PHP tipas |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (vienas) |
string|int |
select, checkbox (keli) |
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 (vienas) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (keli) |
list<array{id: int, url: string, ...}> |
group |
Pavadintos grupės naudoja pabraukimo brūkšnio prefiksus; anoniminės grupės išskleidžiamos į pirminę sritį |
repeater |
list<array{...child fields...}> |
tabs |
Išskleidžiama į pirminę sritį |
API aprašai be realizacijos
Plėtinys pateikiamas su visos Blockstudio viešosios API sistemos tipų aprašais:
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()
Jie suteikia automatinį užbaigimą ir tipų tikrinimą, todėl Blockstudio papildinio šaltinio kodo kompiuteryje turėti nereikia.
Reikalavimai
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(rekomenduojama automatiniam aptikimui)
Paketas automatiškai įdiegia BC Math suderinamumo teikėją. Todėl savoji ext-bcmath pasirenkama, taip pat ir naujoms sugeneruotoms temoms, kuriose temos arba ekstremaliame išankstiniame nustatyme įjungtos JavaScript patikros.