Siirry sisältöön

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

Shell
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:

Shell
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
<?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:

PHP
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:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "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.

Twig
<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.

Blade
<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ä.

HTML
<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:

JSON
{
  "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.

PHP
return [
    'storage' => 'table',
    'fields' => [
        'email' => ['type' => 'string', 'required' => true],
        'name'  => ['type' => 'string'],
    ],
];
PHP
$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.

PHP
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.

PHP
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 id arvoissa, 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/checkbox ilman options– tai populate-arvoa
  • Päällekkäiset kenttätunnukset
  • tabs-kenttä toistimessa suoraan tai ryhmän sisällä, jossa ei ole id-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:

Neon
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):

  • name puuttuu
  • attributes puuttuu tai on tyhjä
  • Virheelliset attribuuttikohteet tai kentän type puuttuu
  • id puuttuu 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ä ilman id-määritystä
  • Sisäkkäiset custom/*-viittaukset puuttuvat, ovat moniselitteisiä tai virheellisiä tai muodostavat syklin

Laajennus JSON (lohkojen laajennukset kohteessa extensions/):

  • Kohdelohko name puuttuu
  • Avain blockstudio puuttuu
  • Avain blockstudio.extend puuttuu

page.json (tiedostopohjaiset sivut):

  • Puuttuu title
  • Puuttuu slug
  • Virheelliset postStatus arvot

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 olla true, false tai 'open')
  • Tukee sekä vanhoja taulukoita että attribuutoituja objektipalautuksia

cron.php:

  • schedule puuttuu määritetyistä tehtävistä
  • callback puuttuu 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ä.

YAML
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:

YAML
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:

Shell
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ä:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "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:

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:

Shell
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ään
  • 1, kun PHPStan ilmoittaa diagnostiikasta
  • 2 virheellisessä 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:

JSON
{
  "$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:

Shell
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:

Shell
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:

Shell
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:

JSON
{"ok":true}

Testi voi ilmoittaa kohdennetusta virheestä:

JSON
{
  "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.

Shell
vendor/bin/blockstudio-agents
Text
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. Tasolla base kuvataan skeema-, malli-, koukku- ja asetussäännöt. Tasolla extreme-theme kuvataan 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:

Shell
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:

Markdown
## 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.