PHPStan
Paplašinājums blockstudio/phpstan nodrošina statisko analīzi Blockstudio projektiem. Tas analīzes laikā validē bloku veidnes, shēmu failus, iestatījumu ceļus un āķu nosaukumus, atklājot kļūdas, pirms tās nonāk izpildlaikā.
Instalēšana
composer require --dev blockstudio/phpstan
7.7. versijas veidņu tipizācijai un paplašinātajām bloku tagu pārbaudēm nepieciešama versija blockstudio/phpstan 0.1.9 vai jaunāka, kā arī PHPStan 2.1.47 vai jaunāka. Atjauniniet pakotni atsevišķi no spraudņa:
composer require --dev blockstudio/phpstan:^0.1.9
Paplašinājums tiek automātiski atrasts, izmantojot PHPStan paplašinājumu instalētāju. Manuāla konfigurēšana nav nepieciešama.
Ko tas pārbauda
Piekļuve veidnes laukiem
Ja PHP fails atrodas blakus block.json, paplašinājums validē katru piekļuvi $a['key'] atbilstoši bloka deklarētajiem atribūtiem.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Paplašinājums zina, ka Blockstudio definē $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview un salu mainīgos, pirms tas iekļauj veidni, tāpēc tieša nolasīšana, piemēram, $a['title'], netiek atzīmēta kā, iespējams, nedefinēta, un $a tips tiek noteikts pēc block.json, kas atrodas blakus veidnei. Struktūra tiek saglabāta arī pēc tipu sašaurināšanas, tāpēc $a['label'] ?? '', isset( $a['cta']['target'] ) un $a['cta']['title'] !== null saglabā deklarētos lauku tipus; veidnē, kurā tiek piešķirta vērtība pašam $a, tiek saglabāts piešķirtais tips. Nepievienojiet /** @var array<string, mixed> $a */ docblock: tas aizstāj šo struktūru ar atvērtu masīvu.
Lauku atslēgas ievēro Blockstudio izpildlaika saplacināšanas noteikumus. tabs un anonīmie group konteineri bez id ir paredzēti tikai attēlošanai, tāpēc to bērnelementu lauki paliek vecāka tvērumā. Nosauktas grupas prefikss bērnelementu atslēgām ir grupas ID:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Atkārtoti izmantojami pielāgoti lauki
Pirms tiek pārbaudītas veidņu atslēgas un masīvu struktūras, tiek izvērstas uz failiem balstītas atsauces custom/*. Paplašinājums nolasa atbilstošo field.json un piemēro tos pašus idStructure, overrides, ligzdoto atsauču, grupu, ciļņu un atkārtotāju noteikumus kā 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" }
}
}
]
}
}
Iegūtās veidņu atslēgas ir title un hero_description. Tās tiek atpazītas PHP, Twig, Blade, bloku tagos un izsecinātajās atribūtu struktūrās.
Ja uz failiem balstītas definīcijas trūkst, tā ir neviennozīmīga, nederīga vai cikliska, tiek parādīta konkrēta kļūda blockstudio.customField.*. Šim blokam tiek izlaistas atkarīgo atslēgu pārbaudes, lai viena neatrisināta definīcija neradītu papildu nepatiesu kļūdu vilni par nezināmiem laukiem.
Definīcijas, kas reģistrētas tikai izpildlaikā, izmantojot filtru blockstudio/fields PHP, statiskajā analīzē nav izsecināmas. Izmantojiet definīciju field.json, ja laukam ir jāpievieno statiski pārbaudītas veidņu atslēgas.
Piekļuve Twig veidnēm
Twig veidnes tiek skenētas automātiski. Anotācija nav nepieciešama.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Piekļuve Blade veidnēm
Blade veidnes tiek skenētas tāpat.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Bloku tagu validācija
Bloku tagi tiek validēti tur, kur tos nolasa Blockstudio: <bs:> un <block> tagos, prefiksu tagos, kas konfigurēti sadaļā blockTags.prefixes (piemēram, <acme-card>, ko izšķir nosaukumvietu secībā tāpat kā izpildlaikā), kā arī aizstājvārdu tagos, PHP, Twig un Blade bloku veidnēs un lapu izkārtojumos. Tiek pārbaudīti arī lapu avoti zem pages/ (index.php, index.html, index.twig, index.blade.php), tostarp HTML elementi, ko projekts sasaista ar blokiem. Iebūvētie UI bloki ir atpazīti, ja ir ieslēgts ui.enabled.
<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) -->
Atribūts tiek pieņemts, ja bloks to deklarē kā lauku (tostarp pielāgotus laukus un laukus, ko bloka tipa lauks pārsūta zem sava idStructure), vai ja Blockstudio to pārsūta uz bloka saknes elementu: data-*, aria-*, id, style, role, title, lang, dir, hidden un tabindex. Veidnēs tiek nodots katrs html-* atribūts; lapu avotos prefikss html- apzīmē tikai vienu no pārsūtītajiem atribūtiem. Par visu pārējo, it īpaši nedeklarētu class, tiek ziņots, jo Blockstudio to saglabā, bet nekad neattēlo.
Izpildlaikā elementu sasaistes un tagu aizstājvārdi tiek reģistrēti filtru PHP darbībās, ko statiskā analīze nevar novērtēt, tāpēc analīze tos nolasa no blockstudio.json. scanPhp pārbauda tagus arī citos projekta PHP, piemēram, moduļu komponentu marķējumā, neziņojot par nezināmiem blokiem tajos:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Elementu var sasaistīt ar bloka nosaukumu vai noteikumiem, ko pārbauda secīgi: uzvar pirmais noteikums, kura atribūts ir elementam, un vienkāršs bloka nosaukums vienmēr atbilst. Elementi, ko projekts nesasaista, saglabā savu pamata bloku un netiek pārbaudīti. Diagnostikas ziņojumos tiek izmantoti blockstudio.blockTag.unknown, blockstudio.blockTag.attribute un blockstudio.blockTag.class.
Datu bāzes ierakstu tipu noteikšana
Db::get() atgriež tipizētu instanci, pamatojoties uz shēmu db.php. Ierakstu struktūras tiek izsecinātas automātiski.
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
Obligātie lauki nav nullējami. Neobligāto lauku tips ir type|null. Lauks id (int) ir vienmēr pieejams. Tāda pati tipizācija darbojas arī sintaksē PHP, kas ir dzimtā Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field būvētājam.
Iestatījumu ceļu validācija
Settings::get() ceļi tiek pārbaudīti atbilstoši zināmajai iestatījumu shēmai.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Āķu nosaukumu validācija
Tiek validēti filtra Blockstudio un darbību āķu nosaukumi.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dinamiskie iestatījumu āķi, piemēram, blockstudio/settings/tailwind/enabled, vienmēr ir atļauti. Āķi, kas nav saistīti ar blockstudio, tiek ignorēti.
Shēmas validācija
Paplašinājums validē katru projekta shēmas failu Blockstudio.
block.json:
- Trūkst lauka
name - Trūkst lauka
type - Trūkst
idvērtību laukos, kuriem tas nepieciešams - Nezināmi lauku tipi
- Lauka rekvizīti, ko lauka tips nepieņem, piemēram,
"translat", nevis"translate", un ieteikums par tuvāko zināmo rekvizītu select/radio/checkboxbezoptionsvaipopulate- Dublēti lauku ID
tabslauks atkārtotājā tieši vai grupā bezid- Nederīgas
pluginDependenciesdeklarācijas
Konteinera lauki, piemēram, group un tabs, kā arī atsauces uz laukiem custom/*, var iztikt bez id, ja tie tikai izvērš vai aptver citus laukus.
Lauku īpašības tiek pārbaudītas, salīdzinot ar īpašībām, ko schemas/block.json deklarē katram iebūvētajam lauka tipam, kā arī ar īpašībām, ko pieņem visi lauki. Šajā pārbaudē nav iekļautas custom/* atsauču iesaiņotāja īpašības un projektā definēti nosaukumvietu lauku tipi. Esošās lauku tipu un pielāgoto atsauču validācijas joprojām tiek veiktas. Identifikatori ir blockstudio.blockJson.property un blockstudio.fieldJson.property.
Tiek pārbaudīti īpašību nosaukumi, ne tikai to vērtības: minimized ir derīgs atkārtotāja laukā, bet teksta laukā par to tiek ziņots. Spraudņa izpildlaika darbība nemainās. Ja projektā iebūvētajiem laukiem apzināti tiek pievienoti savi metadati, apspiediet tikai šos konstatējumus, neatspējojot citas struktūras pārbaudes:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Iebūvētie lauki atkārtoti izmantojamā field.json joprojām tiek pārbaudīti arī tad, ja atsaucei custom/* ir savas iesaiņotāja opcijas. Paplašinājumu faili neietilpst šo īpašību nosaukumu diagnostikas tvērumā; paplašinājumiem paredzētie set noteikumi joprojām ir derīgi.
field.json (atkārtoti izmantojami pielāgoti lauki):
- Trūkst
name - Trūkst vai ir tukšs
attributes - Nederīgi atribūtu objekti vai trūkst lauka
type - Trūkst
idvērtības laukiem, kam tas nepieciešams - Nezināmi lauku tipi
- Lauka īpašības, ko lauka tips nepieņem
tabslauks atkārtotājā — tieši vai grupā bezid- Trūkst ligzdotu
custom/*atsauču, tās ir neviennozīmīgas, nederīgas vai cikliskas
Paplašinājums JSON (bloku paplašinājumi sadaļā extensions/):
- Trūkst
name(mērķa bloks) - Trūkst atslēgas
blockstudio - Trūkst atslēgas
blockstudio.extend
page.json (uz failiem balstītas lapas):
- Trūkst
title - Trūkst
slug - Nederīgas vērtības
postStatus
db.php:
- Trūkst masīva
fields - Nederīgi lauku tipi
- Tiek atbalstīti gan mantotie masīvi, gan
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Nederīgas HTTP metodes
- Nepareiza
publicvērtība (jābūttrue,falsevai'open') - Tiek atbalstīti gan mantotie masīvi, gan atgrieztie objektu atribūti
cron.php:
- Trūkst
schedulekonfigurētajos uzdevumos - Trūkst
callbackkonfigurētajos uzdevumos - Atbalsta gan mantotos masīvus, gan atribūtus saturošus objektus atgriešanas vērtībās
blockstudio.json:
- Saīsinātās Būla vērtības, piemēram,
"tailwind": true(jāizmanto ligzdotā objekta formāts{"enabled": true, "config": ""})
Konfigurācija
Paplašinājums pēc noklusējuma atrod Blockstudio failus analizējamajā projektā.
Ja projektā tiek izmantoti bloki vai atkārtoti lietojami lauki no bibliotēkas ārpus
projekta saknes, pievienojiet bibliotēkas ceļu pie blockstudioScanRoots. Šajā ceļā
meklē gan block.json, gan field.json definīcijas, tāpēc ārējo bloku
atzīmes un to pielāgotos laukus var validēt kopā.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Lai ignorētu failus, izmantojiet PHPStan standarta excludePaths konfigurāciju.
Analīzes sākotnējie iestatījumi
Automātiski atrastais paplašinājums joprojām ir saderīgs pamats. Blockstudio 7.6 pievieno izvēles slāņus, nemainot esošos projektus:
| Sākotnējais iestatījums | Darbība |
|---|---|
base.neon |
Esošās shēmas, veidņu, āķu, iestatījumu un API analīze. |
theme.neon |
Pamats, kam pievienotas WordPress tēmu saknes, stilu galvenes, Blockstudio resursi, selektoru tvērums, lauku noklusējuma vērtības un atkārtotāju robežas. |
extreme-theme.neon |
Tēma, kam pievienoti PHPStan max, nedrošs PHP, izvades ekranošana, Tailwind, JavaScript un Interactivity API pārbaudes. |
wordpress-render.neon |
Galējā tēma, kam pievienota izsaucēja nodrošināta aktīvā WordPress renderēšanas pārbaude. |
Instalējot blockstudio/phpstan, tiek aktivizēts tikai pamata paplašinājums. Iekļaujiet
izvēles slāni esošajā PHPStan konfigurācijā:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths pārvalda tēmu skeneri.
PHPStan standarta excludePaths neatkarīgi pārvalda PHP analīzi.
Kanonomiskās komandas iestatījums phpstan.excludePaths failā blockstudio.json
(un tās opcija --exclude) konfigurē abus slāņus. Relatīvie paraugi tiek atrisināti
attiecībā pret katru konfigurēto sakni, tāpēc tādi ieraksti kā vendor/** ierobežo PHPStan
analīzi, kā arī Blockstudio projekta skenēšanu.
Paraugs, kas norāda uz vienu direktoriju, piemēram, _dist/** vai node_modules/**,
izslēdz šo direktoriju neatkarīgi no tā atrašanās vietas, ne tikai blakus tēmas saknei. Paraugs,
kurā ir slīpsvītra, piemēram, assets/*/docs/**, paliek piesaistīts saknei. Ģenerētie bloku resursi atrodas _dist direktorijā katrā blokā, tāpēc
viena direktorija forma neļauj kompilētajai izvadei nonākt analīzē.
Kanoniskā komanda
Pakotne instalē vendor/bin/blockstudio-phpstan kā analīzes
izpildāmo failu. Tas palaiž base sākotnējo iestatījumu, ja vien projekts neizvēlas citu, tāpēc
pakotnes instalēšana pati par sevi neaktivizē tēmas vai galējās tēmas slāņus:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Sākotnējos iestatījumos paplašinājums jau ir iekļauts. Nepievienojiet
phpstan/extension-installer projektam, kurā tiek palaista kanoniskā komanda:
ja instalētājs ir pieejams, extension.neon tiek ielādēts divreiz un PHPStan apstājas
ar kļūdu “This file is included multiple times” vēl pirms analīzes sākuma.
Komanda pēc noklusējuma iestata PHPStan atmiņas ierobežojumu 1G, lai Composer pārvaldīti
WordPress projekti nepārsniegtu tipisko 128M CLI limitu. Lai to mainītu, pēc -- norādiet
opciju PHPStan, piemēram,
-- --memory-limit=512M --no-progress.
Analīzes ieviešana esošā projektā
Projektā, kas nekad nav analizēts, pirmajā
izpildes reizē parasti tiks atrastas problēmas. Tā vietā, lai pazeminātu sākotnējo iestatījumu, izveidojiet PHPStan bāzes līniju un norādiet
phpstan.configuration uz projekta konfigurāciju, kurā tā ir iekļauta. Jaunam kodam
joprojām būs jāatbilst pilnajam sākotnējam iestatījumam, bet reģistrētās problēmas netraucēs:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Saglabājiet rindu level sākotnējiem iestatījumiem base un theme. Kanoniskā komanda
šiem iestatījumiem nosaka tikai līmeni max, ja nav iekļauta projekta konfigurācija, un
bez līmeņa PHPStan apstājas ar kļūdu “No rules detected”. Sākotnējais iestatījums extreme-theme
pašam nosaka līmeni max.
Relatīvie ceļi tiek atrisināti, sākot no blockstudio.json. Kanoniskā komanda un
pārvaldītais commit āķis šo failu atrod, tāpēc āķis aptur jaunas problēmas, neprasot
vispirms novērst visu uzkrājumu.
Saglabājiet visam projektam paredzētos komandas noklusējuma iestatījumus failā blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Relatīvās saknes tiek atrisinātas attiecībā pret failu, kurā tās deklarētas. Skaidri norādītas CLI vērtības
aizstāj atbilstošās JSON vērtības. Norādiet
--blockstudio-json path/to/project.json alternatīvam konfigurācijas
avotam. Nederīgs JSON, neatbalstītas phpstan atslēgas, nederīgas vērtības un trūkstošs skaidri norādīts avots
paredzami izraisa kļūdu ar izejas kodu 2.
Izvēlieties citu sākotnējo iestatījumu, iekļaujiet projekta konfigurāciju, pievienojiet atkārtoti norādāmas saknes un izņēmumus vai lūdziet PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Aptverošā programma izveido konfigurāciju sistēmas pagaidu direktorijā un izdzēš to, beidzoties izpildei. Tā nekad neieraksta ģenerētu konfigurāciju, bāzes līnijas, āķus vai kešatmiņas analizējamajā projektā. Izsaucēji joprojām var skaidri konfigurēt PHPStan parasto kešatmiņu.
Izejas kodi ir šādi:
0, ja analīze ir sekmīga1, ja PHPStan ziņo par diagnostikas kļūdām2nederīgas lietošanas, konfigurācijas vai procesa izpildes gadījumā
Pārvaldīts apstiprināšanas āķis
Lai padarītu galējās tēmas analīzi par repozitorija commit pārbaudi, aktivizējiet
Blockstudio piederošo āķi failā blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Sinhronizējiet to pēc atkarību instalēšanas vai iestatījuma maiņas:
vendor/bin/blockstudio-githooks sync
Komanda ieraksta ģenerēto pre-commit āķi un īpašumtiesību ierakstu Git koplietotajā direktorijā, iestata core.hooksPath uz pārvaldītā āķa direktoriju un droši savieno to ar iepriekš konfigurēto pre-commit āķi. Atkārtota sinhronizācija atjauno tikai ģenerēto failu, tāpēc pakotnes jauninājumi ir idempotenti.
Iestatiet commit uz false, noņemiet to vai noņemiet blockstudio.json, pēc tam palaidiet
sync, lai atjaunotu reģistrēto āķa ceļu un dzēstu tikai Blockstudio piederošos
failus. Varat arī palaist:
vendor/bin/blockstudio-githooks remove
Lietotāja faili nekad netiek pārrakstīti vai dzēsti. Ja kāds maina
core.hooksPath pēc Blockstudio aktivizēšanas, noņemšanas laikā šis jaunākais
iestatījums tiek saglabāts. Ģenerētais āķis atbalsta saistītās Git darba kopijas un ceļus ar atstarpēm, jo commit izpildes brīdī nosaka aktīvo repozitoriju un projekta sakni. Tas palaiž kanonisko komandu no šīs saknes, tāpēc viens un tas pats phpstan objekts vada gan interaktīvu izpildi, gan commit, neveidojot dublētus ģenerētos argumentus.
Āķis palaiž tikai vendor/bin/blockstudio-phpstan. Blockstudio nepalaiž
formatētāju, un āķis nekad nepārraksta projekta failus. Trūkstošas atkarības un
analīzes kļūdas aptur commit un sniedz noderīgu kļūdas ziņojumu.
Aktīvā WordPress renderēšana
Aktīvais slānis ir apzināti jānorāda. Izsaucējs pārvalda WordPress vidi un nodrošina argv masīvu:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Komanda darbojas bez čaulas un tai jāizvada viens JSON objekts:
{"ok":true}
Pārbaude var ziņot par konkrētu kļūmi:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Nekādas izejas kodi, taimauti, nederīgs JSON un ok: false rada
blockstudio.wordpress.render.
blockstudio.javascript.domContract ziņo par [data-*] atribūta selektoru, ko skripts nodod funkcijai querySelector(), querySelectorAll(), closest() vai matches(), ja analizētajā marķējumā šāda atribūta nav. Marķējums ietver visus analizējamo sakņu PHP, Twig, Blade un HTML failus, kā arī visus React .tsx un .jsx komponentus, izņemot izslēgtos ceļus. Komponenti tiek parsēti: tiek ņemti vērā JSX atribūtu nosaukumi un arī objektu literāļu virkņu atslēgas, tāpēc atribūtu objekts, kas izkliedēts elementā, atbilst selektoram, bet klašu nosaukumi un citas atribūtu vērtības — ne.
Interactivity API pārbaudes lasa tos pašus React komponentus. JSX elementa data-wp-interactive nosaukumvieta tiek uzskatīta par veidnes atsauci blockstudio.interactivity.orphan vajadzībām, un tajā esošās data-wp-* direktīvas tiek atrisinātas, izmantojot tuvāko aptverošo nosaukumvietu vai vērtībā norādītu prefiksu namespace::. Direktīvām ar statisku virknes vērtību, kas norādīta kā JSX atribūts vai atribūtu objekta virknes atslēga, jānosauc esoši krātuves apstrādātāji un ceļi (blockstudio.interactivity.handler, blockstudio.interactivity.binding), un krātuves kods nedrīkst mainīt atribūtus un klases, ar ko tās saistītas (blockstudio.interactivity.derivedState). React izvada atribūtu vērtības, tāpēc par data-wp-context komponentā netiek ziņots, un dinamiskās vērtības netiek pārbaudītas. Nosaukumvietas zem bsui/ pieder komplektā iekļautajiem UI blokiem, kuru krātuves tiek piegādātas kopā ar Blockstudio ārpus analizējamajām saknēm, tāpēc tās nekad netiek uzskatītas par bāreņiem.
Diagnostikas identifikatori
Jaunās sākotnējo iestatījumu diagnostikas saglabā stabilus blockstudio.* ID:
- Tēmas struktūra:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Resursi un lauki:
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
Veiktspēja
Skeneris pieņem parastas, materializētas direktorijas, novērš dublējošās saknes, izlaiž atkarību, būvējumu un kešatmiņas direktoriju kokus, kešo failu nolasījumus atmiņā un kārto diagnostikas ziņojumus paredzamā secībā. Izmantojiet šauru sakņu tvērumu, izslēdziet testa un ģenerētos direktoriju kokus, un lielās repozitorijās iestatiet failu skaita ierobežojumu. JavaScript un Tailwind var atspējot neatkarīgi. Aktīvā renderēšana notiek tikai tad, ja atlasīts attiecīgais sākotnējais iestatījums.
Tēmas, JavaScript un Tailwind diagnostikas rezultāti tiek ziņoti, izmantojot PHPStan rezultātu kešatmiņu. Ja mainīta tikai block.json vai skripts, siltā kešatmiņa var atgriezt iepriekšējo rezultātu. Lai, pārbaudot šādas izmaiņas, apietu kešatmiņu, pēc -- norādiet --debug.
Programmēšanas aģentu projekta līgums
Pakotne instalē trešo izpildāmo failu — vendor/bin/blockstudio-agents. Tas
izveido AGENTS.md ar aprakstu par projektu, kurā tas darbojas. Šī informācija programmēšanas aģentam ir vajadzīga, pirms tas kaut ko maina: ko projekts veido, kuras Blockstudio funkcijas ir iespējotas, ko analīze noraidīs un kuras komandas jāizmanto.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Izvadē nav nekādas fiksētas veidnes. Katra rinda tiek iegūta no viena no trim avotiem:
- Paša projekta faili. Tēma ar
style.cssgalveni, blokiem un failos definētām lapām veidos atšķirīgu dokumentu nekā spraudnis, kas reģistrē tikai blokus. Skeneris faktiski atrastie skaiti, direktorijas, bloku nosaukumvietas un veidņu valodas, izmantojot tās pašas saknes un izņēmumus kā analīzē. blockstudio.json. Aprakstītas tikai iespējotās funkcijas un to konfigurētās vērtības: bloku atzīmju prefiksi un nosaukumvietas, caur kurām tās tiek atrisinātas, Tailwind, komplektā iekļautais UI, redaktora resursu atiestatīšana, kešatmiņas ceļš, veiktspējas profils, statiska iepriekšēja renderēšana un tās dinamiskie ceļi, tēmas noklusējuma vērtības, Content Sync un commit āķis.- Atlasītais
phpstan.preset. Korektuma sadaļa tiek nolasīta tieši no sākotnējo iestatījumu failiem slāni pa slānim, tāpēc tajā uzskaitīti tieši tie noteikumi, ko reģistrē attiecīgais iestatījums. Līmenībaseaprakstīti shēmas, veidņu, āķu un iestatījumu noteikumi. Līmenīextreme-themeaprakstīti arī tēmas struktūras noteikumi, stingrie PHPStan karodziņi, nedrošs PHP, izvades ekranošana, Tailwind un JavaScript. Ja sākotnējam iestatījumam tiek pievienots noteikums, tas parādās arī ģenerētajā dokumentā.
Komandu sadaļā ievērots tas pats princips. wp bs prerender status
parādās, ja ir iespējota statiskā iepriekšējā renderēšana, vendor/bin/blockstudio-githooks sync — ja ir iestatīts githooks.commit, bet wp bs db schemas — ja projektā
faktiski ir db.php.
| Opcija | Darbība |
|---|---|
--root <path> |
Projekta sakne (noklusējums: pašreizējā direktorija) |
--config <path> |
blockstudio.json ceļš (noklusējums: <root>/blockstudio.json) |
--output <path> |
Līguma ceļš (noklusējums: <root>/AGENTS.md) |
--stdout |
Izdrukā līgumu, nevis ieraksta to |
--check |
Iziet ar kodu 1, ja līgums diskā nav aktuāls |
--force |
Aizstāj failu, kas nepieder Blockstudio |
--check padara līgumu par CI pārbaudi, tāpat kā commit āķis padara
analīzi par tādu:
vendor/bin/blockstudio-agents --check
Īpašumtiesības
Ģenerētajā failā ir tāda paša veida marķieris kā pārvaldītajā commit āķī,
un uz to attiecas tas pats noteikums: Blockstudio nekad neaizstāj failu, kuru nav izveidojis.
Ja AGENTS.md pastāvēja pirms komandas vai to manuāli izveidojis autors,
komanda atsakās to apstrādāt, atgriež izejas kodu 2 un atstāj failu neskartu, līdz tiek nodota opcija --force.
Ģenerēšana no jauna ir droša. Fails beidzas ar piezīmju apgabalu, un baiti starp tā marķieriem tiek saglabāti katrā atkārtotā ģenerēšanas reizē:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Izejas kodi ir 0, ja līgums ir ierakstīts, aktuāls vai izdrukāts, 1, ja
--check atrod novecojušu līgumu, un 2 lietošanas, konfigurācijas vai
failu sistēmas kļūdu gadījumā.
Lauku tipu formas
Paplašinājums katru Blockstudio lauka tipu pārveido par konkrētu PHP tipu:
| Lauka tips | PHP tips |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (viens) |
string|int |
select, checkbox (vairāki) |
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 (viens) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (vairāki) |
list<array{id: int, url: string, ...}> |
group |
Nosauktajām grupām izmanto prefiksu ar apakšsvītru; anonīmās grupas sapludina ar vecākapgabalu |
repeater |
list<array{...child fields...}> |
tabs |
Sapludināts ar vecākapgabalu |
API stublas
Paplašinājumā ir iekļautas stublas visam publiskajam Blockstudio API:
bs_render_block(),bs_block_values(),bs_get_group(),bs_get_scoped_class(),bs_db_form(),bs_is_editor(),bs_is_preview(),bs_is_buffering(),bs_strip_render_markers()Db::get(),Db::create(),Db::list(),Db::get_record(),Db::update(),Db::delete()Settings::get(),Settings::get_all()Field_Registry::instance(),Field_Registry::all(),Field_Registry::get()Build::blocks(),Build::extensions(),Build::get_build_dir()
Tās nodrošina automātisko pabeigšanu un tipu pārbaudi, tāpēc jūsu datorā nav vajadzīgs Blockstudio spraudņa avota kods.
Prasības
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(ieteicams automātiskai atrašanai)
Pakotne automātiski instalē savu BC Math saderības nodrošinātāju. Tāpēc vietējais ext-bcmath nav obligāts, arī jaunām ģenerētām tēmām, kurās tēmas vai galējais sākotnējais iestatījums iespējo JavaScript pārbaudes.