PHPStan
blockstudio/phpstan-laajennus tuo staattisen analyysin Blockstudio-projekteihin. Se validoi lohkomallit, skeematiedostot, asetusten polut ja hookien nimet analyysivaiheessa ja havaitsee virheet ennen niiden päätymistä ajonaikaiseen käyttöön.
Asennus
composer require --dev blockstudio/phpstan
Version 7.7 mallien tyypitys ja laajennetut lohkotunnistetarkistukset edellyttävät versiota blockstudio/phpstan 0.1.9 tai uudempaa sekä versiota PHPStan 2.1.47 tai uudempaa. Päivitä paketti erikseen lisäosasta:
composer require --dev blockstudio/phpstan:^0.1.9
Laajennus löytyy automaattisesti kohteen PHPStan laajennusasentimen avulla. Manuaalisia asetuksia ei tarvita.
Tarkistettavat asiat
Mallin kenttäkäyttö
Kun PHP-tiedosto sijaitsee kohteen block.json vieressä, laajennus validoi jokaisen $a['key']-käytön lohkon määritettyjä määritteitä vasten.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Laajennus tietää, että Blockstudio määrittää $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview sekä saareke-muuttujat ennen mallin sisällyttämistä. Siksi suoria lukuja, kuten $a['title'], ei ilmoiteta mahdollisesti määrittelemättömiksi, ja $an tyyppi päätellään mallin vieressä olevasta block.json-tiedostosta. Rakenne säilyy tyypin tarkentuessa, joten $a['label'] ?? '', isset( $a['cta']['target'] ) ja $a['cta']['title'] !== null säilyttävät määritetyt kenttätyypit; jos malli sijoittaa arvon muuttujaan $a, sen tyyppi säilyy. Älä lisää /** @var array<string, mixed> $a */-docblockia: se korvaa rakenteen avoimella taulukolla.
Kenttien avaimet noudattavat kohteen Blockstudio ajonaikaisen litistämisen sääntöjä. tabs– ja nimettömät group-säiliöt ilman id-tunnistetta ovat vain esitystapaa varten, joten niiden lapsikentät jäävät ylätason nimiavaruuteen. Nimetty ryhmä lisää lapsiavainten eteen ryhmän tunnisteen:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Uudelleenkäytettävät mukautetut kentät
Tiedostopohjaiset custom/*-viittaukset avataan ennen mallin avainten ja taulukoiden rakenteiden tarkistusta. Laajennus lukee vastaavan field.json-tiedoston ja soveltaa samoja idStructure-, overrides-, sisäkkäisten viittausten, ryhmien, välilehtien ja toistimien sääntöjä kuin 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" }
}
}
]
}
}
Tuloksena syntyvät mallin avaimet ovat title ja hero_description. Ne tunnistetaan kohteissa PHP, Twig, Blade, lohkotunnisteissa ja päätellyissä määriterakenteissa.
Puuttuvat, monitulkintaiset, virheelliset tai kehämäiset tiedostopohjaiset määritykset tuottavat yksilöidyn blockstudio.customField.*-virheen. Lohkon riippuvaisten avainten tarkistukset ohitetaan, jotta yksi ratkaisematon määritys ei aiheuta uusia virheellisiä ilmoituksia tuntemattomista kentistä.
Vain ajonaikaisesti blockstudio/fields PHP-suodattimen kautta rekisteröityjä määrityksiä ei voida päätellä staattisessa analyysissä. Käytä field.json-määritystä, kun kentän on lisättävä staattisesti tarkistettavia mallin avaimia.
Twig-mallin käyttö
Twig-mallit tarkistetaan automaattisesti. Merkintöjä ei tarvita.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Blade-mallin käyttö
Blade-mallit tarkistetaan samalla tavalla.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Lohkotunnisteiden validointi
Lohkotunnisteet validoidaan niissä kohdissa, joissa Blockstudio lukee niitä: <bs:>– ja <block>-tunnisteissa, kohteessa blockTags.prefixes määritetyissä etuliitetunnisteissa (kuten <acme-card>, jotka ratkaistaan nimiavaruusjärjestyksessä ajonaikaisen toiminnan tapaan) sekä aliastunnisteissa. Tarkistus kattaa PHP-, Twig- ja Blade-lohkotunnisteet sekä sivuasettelut. Myös lähteet polun pages/ alla (index.php, index.html, index.twig, index.blade.php) tarkistetaan, mukaan lukien projektin lohkoihin yhdistämät HTML-elementit. Mukana tulevat UI-lohkot tunnetaan, kun ui.enabled on käytössä.
<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) -->
Määrite hyväksytään, jos lohko määrittää sen kenttänä (mukaan lukien mukautetut kentät ja lohkotyyppisen kentän idStructure-määrityksen eteenpäin välittämät kentät) tai jos Blockstudio välittää sen lohkon juurielementille: data-*, aria-*, id, style, role, title, lang, dir, hidden ja tabindex. Malleissa jokainen html-*-määrite välitetään eteenpäin; sivulähteissä html--etuliite nimeää vain yhden eteenpäin välitetyistä määritteistä. Kaikki muut ilmoitetaan, etenkin määrittelemätön class, koska Blockstudio tallentaa sen eikä koskaan renderöi sitä.
Ajonaikainen ympäristö rekisteröi elementtien yhdistämiset ja tunnistealiakset PHP-suodattimissa, joita staattinen analyysi ei voi suorittaa. Siksi analyysi lukee määritykset kohteesta blockstudio.json. scanPhp tarkistaa tunnisteet myös projektin muissa PHP-tiedostoissa, kuten moduulien komponenttimerkinnöissä, ilmoittamatta niissä tuntemattomista lohkoista:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Elementti yhdistetään lohkon nimeen tai järjestyksessä kokeiltaviin sääntöihin: ensimmäinen sääntö, jonka määrite elementillä on, voittaa, ja pelkkä lohkon nimi täsmää aina. Elementit, joita projekti ei yhdistä, säilyttävät ydintason lohkonsa eikä niitä tarkisteta. Diagnostiikassa käytetään kohteita blockstudio.blockTag.unknown, blockstudio.blockTag.attribute ja blockstudio.blockTag.class.
Tietokantatietueiden tyypitys
Db::get() palauttaa tyypitetyn instanssin db.php-skeeman perusteella. Tietueiden rakenteet päätellään automaattisesti.
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
Pakolliset kentät eivät voi olla null-arvoja. Valinnaiset kentät ovat type|null. id-kenttä (int) on aina mukana. Sama tyypitys toimii myös PHP-natiivissa Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field-rakentajasynaksissa.
Asetuspolkujen validointi
Settings::get()-polut tarkistetaan tunnettua asetusskeemaa vasten.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Hookien nimien validointi
Blockstudio-suodattimen ja toimintojen hookien nimet validoidaan.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Dynaamiset asetus-hookit, kuten blockstudio/settings/tailwind/enabled, sallitaan aina. Muut kuin blockstudio-hookit ohitetaan.
Skeeman validointi
Laajennus validoi projektin jokaisen Blockstudio-skeematiedoston.
block.json:
- Puuttuva
name-kenttä - Puuttuva kenttä
type - Puuttuva
idarvoissa, jotka sitä edellyttävät - Tuntemattomat kenttätyypit
- Kenttätyypin hylkäämät kentän ominaisuudet, kuten
"translat"arvon"translate"sijaan; ehdotuksena annetaan lähin tunnettu ominaisuus select/radio/checkboxilmanoptions– taipopulate-arvoa- Päällekkäiset kenttätunnukset
tabs-kenttä toistimessa suoraan tai ryhmän sisällä, jossa ei oleid-arvoa- Virheelliset
pluginDependencies-määritykset
Säiliökentistä, kuten group ja tabs, sekä custom/*-kenttäviittauksista voidaan jättää id pois, jos ne vain laajentavat tai käärivät muita kenttiä.
Kentän ominaisuuksia verrataan ominaisuuksiin, jotka schemas/block.json määrittää kullekin sisäänrakennetulle kenttätyypille, sekä ominaisuuksiin, jotka kaikki kentät hyväksyvät. custom/*-viittausten käärekohtaiset ominaisuudet ja projektissa määritetyt nimiavaruudelliset kenttätyypit jäävät tämän tarkistuksen ulkopuolelle. Olemassa olevat kenttätyyppien ja mukautettujen viittausten tarkistukset ovat edelleen käytössä. Tunnisteet ovat blockstudio.blockJson.property ja blockstudio.fieldJson.property.
Tässä tarkistetaan ominaisuuksien nimet, ei vain niiden arvoja: minimized kelpaa toistimelle, mutta siitä ilmoitetaan tekstikentässä. Lisäosan ajonaikainen toiminta ei muutu. Jos projekti liittää tarkoituksella omaa metatietoaan sisäänrakennettuihin kenttiin, voit vaientaa vain nämä havainnot poistamatta käytöstä muita rakennetarkistuksia:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Uudelleenkäytettävän field.json-elementin sisällä olevat sisäänrakennetut kentät tarkistetaan edelleen, vaikka custom/*-viittauksella olisi omat kääreasetuksensa. Laajennustiedostot eivät kuulu näiden ominaisuusnimidiagnostiikkojen piiriin; laajennuskohtaiset set-säännöt ovat edelleen voimassa.
field.json (uudelleenkäytettävät mukautetut kentät):
namepuuttuuattributespuuttuu tai on tyhjä- Virheelliset attribuuttikohteet tai kentän
typepuuttuu idpuuttuu arvoa sisältävistä kentistä, joissa se vaaditaan- Tuntemattomat kenttätyypit
- Kentän ominaisuudet, joita kenttätyyppi ei hyväksy
tabs-kenttä toistimen sisällä joko suoraan tai ryhmän sisällä ilmanid-määritystä- Sisäkkäiset
custom/*-viittaukset puuttuvat, ovat moniselitteisiä tai virheellisiä tai muodostavat syklin
Laajennus JSON (lohkojen laajennukset kohteessa extensions/):
- Kohdelohko
namepuuttuu - Avain
blockstudiopuuttuu - Avain
blockstudio.extendpuuttuu
page.json (tiedostopohjaiset sivut):
- Puuttuu
title - Puuttuu
slug - Virheelliset
postStatusarvot
db.php:
fields-taulukko puuttuu- Virheelliset kenttätyypit
- Tukee sekä vanhoja taulukoita että
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Virheelliset HTTP-menetelmät
- Väärä
public-arvo (täytyy ollatrue,falsetai'open') - Tukee sekä vanhoja taulukoita että attribuutoituja objektipalautuksia
cron.php:
schedulepuuttuu määritetyistä tehtävistäcallbackpuuttuu määritetyistä tehtävistä- Tukee sekä vanhoja taulukoita että attribuutoituja objektipalautuksia
blockstudio.json:
- Lyhennetyt totuusarvot, kuten
"tailwind": true(käytä sisäkkäisen objektin muotoa{"enabled": true, "config": ""})
Määritykset
Laajennus etsii oletusarvoisesti Blockstudio-tiedostot analysoitavasta projektista.
Kun projekti käyttää lohkoja tai uudelleenkäytettäviä kenttiä projektin juurikansion
ulkopuolisesta kirjastosta, lisää kirjaston polku kohtaan blockstudioScanRoots. Polku
skannataan sekä block.json– että field.json-määritelmien varalta, jotta ulkoisten lohkojen
merkinnät ja niiden mukautetut kentät voidaan validoida yhdessä.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Voit ohittaa tiedostoja käyttämällä PHPStan-määrityksen tavallista excludePaths-asetusta.
Analyysin esiasetukset
Automaattisesti löydetty laajennus säilyy yhteensopivana perustana. Blockstudio 7.6 lisää valinnaisia tasoja muuttamatta olemassa olevia projekteja:
| Esiasetus | Toiminta |
|---|---|
base.neon |
Olemassa olevien skeemojen, mallien, koukkujen, asetusten ja API-analyysi. |
theme.neon |
Perusta sekä WordPress-teemajuuret, tyylien otsakkeet, Blockstudio-resurssit, valitsimien rajaus, kenttien oletusarvot ja toistimen rajat. |
extreme-theme.neon |
Teema sekä PHPStan max, vaarallinen PHP, tulosteen escapointi, Tailwind, JavaScript ja Interactivityn API-tarkistukset. |
wordpress-render.neon |
Äärimmäinen teema sekä kutsujan tarjoama reaaliaikainen WordPress-renderöintitesti. |
Asentamalla blockstudio/phpstan otat käyttöön vain peruslaajennuksen. Lisää olemassa olevaan PHPStan-kokoonpanoon valinnainen kerros:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths ohjaa teeman skanneria.
PHPStan-määrityksen tavallinen excludePaths ohjaa PHP-analyysiä itsenäisesti.
Vakiokomennon phpstan.excludePaths-asetus tiedostossa blockstudio.json
(samoin kuin sen --exclude-valinta) määrittää molemmat tasot. Suhteelliset kuviot ratkaistaan
jokaisen määritetyn juuren mukaan, joten merkinnät kuten vendor/** rajaavat PHPStan-analyysiä
sekä Blockstudio-projektiskannausta.
Yhden hakemiston nimeävä kuvio, kuten _dist/** tai node_modules/**,
sulkee kyseisen hakemiston pois kaikkialta, missä se esiintyy, ei vain teeman juuren vierestä. Vinoviivan
sisältävä kuvio, kuten assets/*/docs/**, pysyy sidottuna juureen. Luodut lohkoresurssit sijaitsevat
en kunkin lohkon sisäisessä _dist-hakemistossa, joten yhden hakemiston muoto pitää käännetyn tulosteen analyysin ulkopuolella.
Vakiokomento
Paketti asentaa vendor/bin/blockstudio-phpstan-analyysiohjelman.
Se käyttää base-esiasetusta, ellei projekti valitse muuta, joten
paketin asentaminen ei itsessään ota käyttöön teema- tai äärimmäisen teeman tasoja:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Esiasetukset sisältävät itse laajennuksen. Älä lisää
phpstan/extension-installer projektiin, joka käyttää vakiokomentoa:
asentimen ollessa käytössä extension.neon ladataan kahdesti ja PHPStan pysähtyy
ilmoitukseen ”This file is included multiple times” ennen analyysin aloittamista.
Komento asettaa PHPStan-arvoksi 1G muistirajan, jotta Composer-hallinnoidut
WordPress-projektit eivät peri tavanomaista 128M CLI-rajaa. Voit ohittaa sen antamalla
nimenomaisen PHPStan-valinnan komennon -- jälkeen, esimerkiksi
-- --memory-limit=512M --no-progress.
Analyysin käyttöönotto olemassa olevassa projektissa
Projektissa, jota ei ole koskaan analysoitu, löytyy yleensä huomautuksia ensimmäisellä
ajokerralla. Sen sijaan, että laskisit esiasetuksen tasoa, luo PHPStan-vertailupohja ja määritä
phpstan.configuration käyttämään projektimääritystä, joka sisältää sen. Uutta koodia
arvioidaan sen jälkeen täydellä esiasetuksella, ja tallennetut havainnot eivät häiritse työtä:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Säilytä level-rivi base– ja theme-esiasetuksia varten. Vakiokomento
asettaa niille tason max vain, jos projektimääritystä ei ole mukana, ja ilman tasoa
PHPStan pysähtyy ilmoitukseen ”No rules detected”. extreme-theme-esiasetus
asettaa itse tason max.
Suhteelliset polut ratkaistaan sijainnista blockstudio.json. Sekä vakiokomento että
hallittu commit-koukku poimivat tiedoston, joten koukku estää uusien havaintojen hyväksymisen
vaatimatta ensin vanhojen havaintojen korjaamista.
Pidä projektinlaajuiset komentojen oletusarvot tiedostossa blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Suhteelliset juuret ratkaistaan ne määrittävän tiedoston sijainnista. Nimenomaiset CLI-arvot
korvaavat vastaavat JSON-arvot. Anna --blockstudio-json path/to/project.json vaihtoehtoista määrityslähdettä
varten. Virheelliset JSON, tuetut toimimattomat phpstan-avaimet, virheelliset arvot ja
puuttuva nimenomainen lähde aiheuttavat ennakoitavasti poistumiskoodin 2.
Valitse toinen esiasetus, lisää projektimääritys, lisää toistettavia juuria ja poissulkuja tai pyydä PHPStan-komennolta JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Käärintäkomento kokoaa määrityksen järjestelmän väliaikaishakemistossa ja poistaa sen lopetettaessa. Se ei koskaan kirjoita luotua määritystä, vertailupohjia, koukkuja eikä välimuisteja analysoitavaan projektiin. Kutsujat voivat silti määrittää PHPStan-komennon tavallisen välimuistin erikseen.
Poistumiskoodit ovat seuraavat:
0, kun analyysi läpäistään1, kun PHPStan ilmoittaa diagnostiikasta2virheellisessä käytössä, määrityksessä tai prosessin suorituksessa
Hallittu commit-koukku
Ota blockstudio.json-määrityksessä käyttöön Blockstudio-hallinnoima koukku,
jotta äärimmäisen teeman analyysistä tulee tietovaraston commit-portti:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Synkronoi se riippuvuuksien asentamisen tai asetuksen muuttamisen jälkeen:
vendor/bin/blockstudio-githooks sync
Komento kirjoittaa luodun pre-commit-koukun ja omistustietueen hakemiston
Git yhteiseen osaan, asettaa core.hooksPath-arvoksi hallitun koukun hakemiston
ja ketjuttaa turvallisesti aiemmin määritetyn pre-commit-koukun. Toistuvat synkronoinnit
päivittävät vain luodun tiedoston, joten paketin päivitykset ovat idempotentteja.
Aseta commit arvoon false, poista se tai poista blockstudio.json ja suorita
sync palauttaaksesi tallennetun koukkupolun ja poistaaksesi vain Blockstudio-hallinnoidut
tiedostot. Voit myös suorittaa:
vendor/bin/blockstudio-githooks remove
Käyttäjien omistamia tiedostoja ei koskaan korvata eikä poisteta. Jos joku muuttaa
core.hooksPath-asetusta sen jälkeen, kun Blockstudio on otettu käyttöön, poistaminen säilyttää uuden
asetuksen. Luotu koukku tukee linkitettyjä Git-työkopioita ja välilyöntejä sisältäviä polkuja
ratkaisemalla aktiivisen tietovaraston ja projektin juuren commit-hetkellä. Se suorittaa
vakiokomennon kyseisestä juuresta, joten sama phpstan-objekti hallitsee vuorovaikutteisia ajoja ja committeja ilman kahteen kertaan luotuja argumentteja.
Koukku suorittaa vain vendor/bin/blockstudio-phpstan-komennon. Blockstudio ei suorita
muotoilijaa, eikä koukku koskaan kirjoita projektin tiedostoja uudelleen. Puuttuvat riippuvuudet ja
analyysin virheet estävät commitin ja antavat korjaustoimenpiteisiin ohjaavan virheilmoituksen.
Reaaliaikainen WordPress-renderöinti
Reaaliaikainen kerros on tarkoituksella erikseen määritettävä. Kutsuja omistaa WordPress-ympäristön ja antaa argv-taulukon:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Komento suoritetaan ilman komentotulkkia, ja sen on tulostettava yksi JSON-objekti:
{"ok":true}
Testi voi ilmoittaa kohdennetusta virheestä:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Nollasta poikkeavat poistumiskoodit, aikakatkaisut, virheelliset JSON-arvot ja ok: false tuottavat
blockstudio.wordpress.render-tuloksen.
blockstudio.javascript.domContract ilmoittaa [data-*]-attribuutin valitsimesta, jonka skripti välittää funktiolle querySelector(), querySelectorAll(), closest() tai matches(), kun mikään analysoitu merkintä ei sisällä kyseistä attribuuttia. Merkintöihin kuuluvat kaikki PHP-, Twig-, Blade- ja HTML-tiedostot sekä kaikki analysoitavien juurien alla olevat React .tsx– ja .jsx-komponentit poissuljettuja polkuja lukuun ottamatta. Komponentit jäsennetään: JSX-attribuuttien nimet lasketaan mukaan, samoin objektiliteraalien merkkijonoavaimet. Siksi elementtiin levitettävä attribuuttiobjekti täyttää valitsimen ehdon, kun taas luokkanimet ja muut attribuuttiarvot eivät.
Interaktiivisuuden API-tarkistukset lukevat samoja React-komponentteja. JSX-elementin data-wp-interactive-nimiavaruus lasketaan malliviittaukseksi blockstudio.interactivity.orphan-tarkistuksessa, ja sen sisällä olevat data-wp-*-direktiivit selvitetään lähimmän ympäröivän nimiavaruuden mukaan tai arvossa olevan namespace::-etuliitteen perusteella. Staattisen merkkijonoarvon sisältävien direktiivien, jotka on kirjoitettu JSX-attribuutiksi tai attribuuttiobjektin merkkijonoavaimeksi, on viitattava olemassa oleviin tilan käsittelijöihin ja polkuihin (blockstudio.interactivity.handler, blockstudio.interactivity.binding), eikä tilakoodi saa muuttaa attribuutteja ja luokkia, joihin se sitoutuu (blockstudio.interactivity.derivedState). React pakenee attribuuttiarvot, joten komponentin data-wp-context ei aiheuta ilmoitusta, eikä dynaamisia arvoja tarkisteta. bsui/-nimenavaruudet kuuluvat mukana toimitettuihin UI-lohkoihin, joiden tilat toimitetaan Blockstudio-paketin mukana analysoitavien juurien ulkopuolella, joten ne eivät koskaan jää orvoiksi.
Diagnostiikkatunnisteet
Uudet esiasetuksen diagnostiikat säilyttävät vakaat blockstudio.*-tunnisteet:
- Teeman rakenne:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Resurssit ja kentät:
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 - Interaktiivisuus:
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
Suorituskyky
Skanneri hyväksyy tavalliset levylle kirjoitetut hakemistot, poistaa päällekkäiset juuret, ohittaa riippuvuus-, build- ja välimuistipuut, tallentaa tiedostoluvut välimuistiin muistissa ja järjestää diagnostiikan ennakoitavasti. Pidä juuret suppeina, sulje pois testidata- ja luodut hakemistot ja aseta suurissa tietovarastoissa tiedostoraja. JavaScript ja Tailwind voidaan poistaa käytöstä toisistaan riippumatta. Reaaliaikainen renderöinti suoritetaan vain, kun sen esiasetus on valittu.
Teema-, JavaScript- ja Tailwind-diagnostiikat ilmoitetaan PHPStan-tulosten
välimuistin kautta. Kun muutat vain block.json-tiedostoa tai komentosarjaa, lämmin
välimuisti voi ilmoittaa aiemman tuloksen. Ohita välimuisti välittämällä
--debug kohdan -- jälkeen, kun tarkistat tällaiset muutokset.
Koodausagenttien projektisopimus
Paketti asentaa kolmannen suoritettavan tiedoston, vendor/bin/blockstudio-agents. Se
kirjoittaa AGENTS.md-kuvauksen projektista, jossa sitä käytetään. Koodausagentti tarvitsee sen ennen kuin se koskee mihinkään: mitä projekti tuottaa, mitkä Blockstudio-ominaisuudet ovat käytössä, mitä analyysi hylkää ja mitä komentoja sovelletaan.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Tulosteen sisältöä ei ole kiinnitetty mallipohjaan. Jokainen rivi johdetaan yhdestä kolmesta lähteestä:
- Projektin omat tiedostot. Teema, jossa on
style.css-otsake, lohkoja ja tiedostoihin perustuvia sivuja, tuottaa erilaisen dokumentin kuin lisäosa, joka rekisteröi lohkoja eikä mitään muuta. Määrät, hakemistot, lohkojen nimiavaruudet ja mallipohjakielet ovat sitä, mitä skanneri todella löysi samoja juuria ja poissulkuja käyttäen kuin analyysissä. blockstudio.json. Kuvauksessa esitetään vain käytössä olevat ominaisuudet määritettyine arvoineen: lohkotunnisteiden etuliitteet ja nimiavaruudet, joiden kautta ne ratkeavat, Tailwind, mukana toimitettu UI, editorin resurssien nollaus, välimuistin polku, suorituskykyprofiili, staattinen esirenderöinti ja sen dynaamiset polut, teeman oletusarvot, Content Sync ja commit-koukku.- Valittu
phpstan.preset. Oikeellisuutta käsittelevä osio luetaan suoraan esiasetustiedostoista kerros kerrokselta, joten siinä luetellaan täsmälleen kyseisen esiasetuksen rekisteröimät säännöt. Tasollabasekuvataan skeema-, malli-, koukku- ja asetussäännöt. Tasollaextreme-themekuvataan lisäksi teeman rakennesäännöt, tiukat PHPStan-liput, vaarallinen PHP, tulosteen escapointi, Tailwind ja JavaScript. Kun esiasetukseen lisätään sääntö, myös luotu dokumentti muuttuu sen mukaisesti.
Komento-osio noudattaa samaa periaatetta. wp bs prerender status
on mukana, kun staattinen esirenderöinti on käytössä, vendor/bin/blockstudio-githooks sync kun githooks.commit on määritetty ja wp bs db schemas kun projektissa
on todella db.php.
| Valinta | Toiminta |
|---|---|
--root <path> |
Projektin juuri (oletus: nykyinen hakemisto) |
--config <path> |
blockstudio.json-polku (oletus: <root>/blockstudio.json) |
--output <path> |
Sopimuspolku (oletus: <root>/AGENTS.md) |
--stdout |
Tulosta sopimus kirjoittamisen sijaan |
--check |
Poistu koodilla 1, jos levyllä oleva sopimus ei ole ajan tasalla |
--force |
Korvaa tiedosto, jonka Blockstudio omistaa |
--check tekee sopimuksesta CI-portin samalla tavoin kuin commit-koukku tekee
analyysistä portin:
vendor/bin/blockstudio-agents --check
Omistajuus
Luotu tiedosto sisältää samantyyppisen tunnisteen kuin hallittu commit-koukku,
ja sama sääntö pätee: Blockstudio ei koskaan korvaa tiedostoa, jota se ei ole kirjoittanut.
Jos AGENTS.md on olemassa jo ennen komennon käyttöä tai tekijä on kirjoittanut sen käsin,
komento kieltäytyy käsittelemästä sitä poistumiskoodilla 2 ja jättää sen ennalleen, kunnes annetaan --force.
Uudelleenluonti on turvallista. Tiedoston lopussa on muistiinpanoalue, ja sen merkkien väliin jäävät tavut säilyvät jokaisella uudelleenluontikerralla:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Poistumiskoodit ovat 0, kun sopimus kirjoitetaan, on ajan tasalla tai tulostetaan, 1, kun
--check löytää vanhentuneen sopimuksen, ja 2 käyttö-, määritys- tai
filejärjestelmävirheissä.
Kenttätyyppien rakenteet
Laajennus yhdistää jokaisen Blockstudio-kenttätyypin konkreettiseen PHP-tyyppiin:
| Kenttätyyppi | PHP-tyyppi |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (yksittäinen) |
string|int |
select, checkbox (useita) |
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 (yksittäinen) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (useita) |
list<array{id: int, url: string, ...}> |
group |
Nimetyt ryhmät käyttävät alaviivalla alkavia etuliitteitä; nimettömät ryhmät litistetään ylemmän tason nimiavaruuteen |
repeater |
list<array{...child fields...}> |
tabs |
Litistetään ylemmän tason nimiavaruuteen |
API-tyngät
Laajennuksen mukana toimitetaan tyngät koko Blockstudio-julkiselle API-rajapinnalle:
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()
Ne tarjoavat automaattisen täydennyksen ja tyyppitarkistuksen ilman, että Blockstudio-lisäosan lähdekoodia tarvitsee olla koneellasi.
Vaatimukset
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(suositellaan automaattista löytämistä varten)
Paketti asentaa BC Math -yhteensopivuuspalveluntarjoajan automaattisesti. Siksi
natiivia ext-bcmath-tukea ei tarvita; tämä koskee myös uusia luotuja teemoja, joissa
JavaScript-tarkistukset otetaan käyttöön teema- tai extreme-esiasetuksella.