Liigu sisu juurde

PHPStan

Laiendus blockstudio/phpstan lisab projektidele Blockstudio staatilise analüüsi. See valideerib analüüsi ajal plokimalle, skeemifaile, seadistuste teid ja hook’ide nimesid, leides vead enne nende jõudmist käitusaega.

Paigaldamine

Shell
composer require --dev blockstudio/phpstan

Versiooni 7.7 mallide tüübistus ja laiendatud plokisiltide kontroll nõuavad versiooni blockstudio/phpstan 0.1.9 või uuemat ning versiooni PHPStan 2.1.47 või uuemat. Uuendage pakett pluginast eraldi:

Shell
composer require --dev blockstudio/phpstan:^0.1.9

Laiendus leitakse automaatselt PHPStan laienduste paigaldaja kaudu. Käsitsi seadistamine pole vajalik.

Mida see kontrollib

Malliväljadele juurdepääs

Kui fail PHP asub faili block.json kõrval, valideerib laiendus iga juurdepääsu $a['key'] ploki deklareeritud atribuutide põhjal.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

Laiendus teab, et Blockstudio määratleb väljad $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview ja saare muutujad enne malli kaasamist. Seetõttu ei märgita otseseid lugemisi, näiteks $a['title'], võimalikuna määratlemata ning $a tüüp tuletatakse malli kõrval olevast block.json-st. Kuju säilib kitsendamisel, seega säilitavad $a['label'] ?? '', isset( $a['cta']['target'] ) ja $a['cta']['title'] !== null deklareeritud väljatüübid; kui mall määrab ise $a, jääb sellele omistatud tüüp alles. Ärge lisage /** @var array<string, mixed> $a */ docblock’i: see asendab kuju avatud massiiviga.

Võtmeväljad järgivad käitusaja Blockstudio tasandamisreegleid. tabs ja nimeta konteinerid group, millel puudub id, on üksnes esituslikud, seega jäävad nende alamväljad ülemüksuse ulatusse. Nimega rühma puhul lisatakse alamväljade võtmetele rühma ID eesliide:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Korduvkasutatavad kohandatud väljad

Failipõhised viited custom/* laiendatakse enne mallivõtmete ja massiivikujude kontrollimist. Laiendus loeb vastava field.json ning rakendab samu reegleid nagu Blockstudio: idStructure, overrides, pesastatud viited, rühmad, vahekaardid ja kordajad.

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" }
        }
      }
    ]
  }
}

Tulemuseks olevad mallivõtmed on title ja hero_description. Need tuntakse ära kohtades PHP, Twig, Blade, plokisiltides ja tuletatud atribuudi kujudes.

Puuduv, mitmetähenduslik, vigane või tsükliline failipõhine määratlus tekitab konkreetse vea blockstudio.customField.*. Selle ploki sõltuvate võtmete kontrollid jäetakse vahele, et üks lahendamata määratlus ei tekitaks täiendavaid valeteateid tundmatute väljade kohta.

Määratlusi, mis registreeritakse ainult käitusajal filtri blockstudio/fields PHP kaudu, ei saa staatilise analüüsiga tuletada. Kasutage määratlust field.json, kui väli peab lisama staatiliselt kontrollitud mallivõtmed.

Mallile Twig juurdepääs

Malle Twig skannitakse automaatselt. Anotatsiooni pole vaja.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Mallile Blade juurdepääs

Malle Blade skannitakse samal viisil.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Plokisiltide valideerimine

Plokisilte valideeritakse seal, kus Blockstudio neid loeb: sildid <bs:> ja <block>, failis blockTags.prefixes seadistatud eesliitesildid (näiteks <acme-card>, mis lahendatakse nimeruumide järjekorras nagu käitusajal) ning aliasnimed mallides PHP, Twig ja Blade ning lehepaigutustes. Kontrollitakse ka allikaid lehtedes, mis asuvad allpool pages/ (index.php, index.html, index.twig, index.blade.php), sealhulgas elemente HTML, mille projekt seostab plokkidega. Komplekti kuuluvaid plokke UI tuntakse, kui ui.enabled on sisse lülitatud.

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

Atribuut on lubatud, kui plokk deklareerib selle väljana (sealhulgas kohandatud väljad ja plokitüübiga välja poolt oma idStructure kaudu edastatavad väljad) või kui Blockstudio edastab selle ploki juurelemendile: data-*, aria-*, id, style, role, title, lang, dir, hidden ja tabindex. Mallides pääsevad läbi kõik atribuudid html-*; leheallikates tähistab eesliide html- ainult üht edastatud atribuuti. Kõigest muust, eriti deklareerimata atribuudist class, antakse teada, sest Blockstudio salvestab selle, kuid ei renderda kunagi.

Käitusajal registreerib süsteem elementide vastendused ja sildialiasnimed filtrites PHP, mida staatiline analüüs hinnata ei saa, seega loeb analüüs need failist blockstudio.json. Samuti kontrollib scanPhp silte muudes projekti PHP-failides, näiteks moodulite komponendimärgistuses, ilma seal tundmatute plokkide kohta teateid esitamata:

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
    }
  }
}

Element vastendatakse ploki nime või reeglitega, mida kontrollitakse järjekorras: võidab esimene reegel, mille atribuuti element sisaldab, ja tavaline ploki nimi sobib alati. Elemente, mida projekt ei vastenda, ei kontrollita ning need säilitavad oma tuumploki. Diagnostikateadetes kasutatakse blockstudio.blockTag.unknown, blockstudio.blockTag.attribute ja blockstudio.blockTag.class.

Andmebaasikirjete tüübistus

Db::get() tagastab skeemi db.php põhjal tüübistatud eksemplari. Kirjete kujud tuletatakse automaatselt.

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

Kohustuslikud väljad ei saa olla nullväärtusega. Valikulised väljad on type|null. Väli id (int) on alati olemas. Sama tüübistus toimib ka PHP-põhise süntaksiga Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Seadete tee valideerimine

Settings::get() teid kontrollitakse tuntud seadistuste skeemi põhjal.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Hooki nime valideerimine

Blockstudio filtrite ja tegevuste hook’ide nimesid valideeritakse.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

Dünaamilised seadistuste hook’id, näiteks blockstudio/settings/tailwind/enabled, on alati lubatud. Muid kui blockstudio hook’e eiratakse.

Skeemi valideerimine

Laiendus valideerib projekti kõik skeemifailid Blockstudio.

block.json:

  • Puuduv name väli
  • Puuduv väli type
  • Väärtusväljadelt puuduv id, kui see on nõutav
  • Tundmatud väljatüübid
  • Välja omadused, mida väljatüüp ei aktsepteeri, näiteks "translat" asemel "translate"; soovitusena esitatakse lähim teadaolev omadus
  • select/radio/checkbox ilma options või populate-ta
  • Korduvad välja ID-d
  • tabs väli kordaja sees, otse või grupis, millel puudub id
  • Vigased pluginDependencies deklaratsioonid

Konteinerväljad, nagu group ja tabs, ning väljade viited custom/* võivad jätta määramata id, kui need laiendavad või ümbritsevad üksnes teisi välju.

Väljade atribuute kontrollitakse iga sisseehitatud väljatüübi jaoks schemas/block.json deklareeritud atribuutide ning kõigi väljade puhul aktsepteeritavate atribuutide alusel. custom/* viidete ümbrise omadused ja projektis määratletud nimeruumiga väljatüübid jäävad selle kontrolli alt välja. Olemasolev väljatüüpide ja kohandatud viidete valideerimine kehtib endiselt. Tunnused on blockstudio.blockJson.property ja blockstudio.fieldJson.property.

See kontrollib atribuutide nimesid, mitte ainult nende väärtusi: minimized sobib kordusvälja juurde, kuid tekstivälja korral antakse sellest teada. Plugina käitusaegne käitumine ei muutu. Kui projekt lisab sisseehitatud väljadele teadlikult oma metaandmeid, saab ainult need leiud välja lülitada, keelamata muid struktuurikontrolle:

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Taaskasutatava field.json sees olevaid sisseehitatud välju kontrollitakse endiselt, isegi kui viitel custom/* on oma ümbrise valikud. Laiendusfailid jäävad nende atribuudinime diagnostikate ulatusest välja; laienduspõhised set reeglid kehtivad endiselt.

field.json (korduvkasutatavad kohandatud väljad):

  • Puudub name
  • attributes puudub või on tühi
  • Vigased atribuutide objektid või puuduv välja type
  • Puudub id väärtusväljadel, mis seda vajavad
  • Tundmatud väljatüübid
  • Välja atribuudid, mida väljatüüp ei aktsepteeri
  • tabs väli kordusvälja sees otse või rühmas, millel puudub id
  • Puuduvad, mitmetähenduslikud, vigased või tsüklilised pesastatud custom/* viited

Laiendi JSON (plokilaiendid asukohas extensions/):

  • Puudub name (sihtplokk)
  • Puudub võtmeväli blockstudio
  • Puudub võtmeväli blockstudio.extend

page.json (failipõhised lehed):

  • Puudub title
  • Puudub slug
  • Vigased postStatus väärtused

db.php:

  • Puudub fields massiiv
  • Vigased väljatüübid
  • Toetab nii pärandmassiive kui ka Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Vigased HTTP meetodid
  • Vale public väärtus (peab olema true, false või 'open')
  • Toetab nii pärandmassiive kui ka atribuutidega objektide tagastusi

cron.php:

  • Konfigureeritud ülesannetel puudub schedule
  • Konfigureeritud ülesannetel puudub callback
  • Toetab nii pärandmassiive kui ka atribuutidega objektide tagastusi

blockstudio.json:

  • Lühikesed tõeväärtused, näiteks "tailwind": true (kasutage pesastatud objekti vormingut {"enabled": true, "config": ""})

Konfiguratsioon

Laiendus leiab analüüsitavas projektis vaikimisi üles Blockstudio failid. Kui projekt kasutab plokke või korduvkasutatavaid välju teegist, mis asub väljaspool projekti juurkausta, lisage teegi asukoht väljale blockstudioScanRoots. Asukohta skannitakse nii block.json kui ka field.json määratluste leidmiseks, nii et välised plokisildid ja nende kohandatud väljad saab koos valideerida.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

Failide eiramiseks kasutage PHPStan standardset excludePaths konfiguratsiooni.

Analüüsi eelseadistused

Automaatselt leitav laiendus jääb tagasiühilduvaks põhialuseks. Blockstudio 7.6 lisab valikulised kihid olemasolevaid projekte muutmata:

Eelseadistus Käitumine
base.neon Olemasoleva skeemi, mallide, hook’ide, seadete ja API analüüs.
theme.neon Põhialus koos WordPress teemajuurte, stiilipäiste, Blockstudio varade, selektorite ulatuse piiramise, väljade vaikeväärtuste ja korduvväljade piirangutega.
extreme-theme.neon Teema koos PHPStan max kontrollide, ohtliku PHP, väljundi paomärkide, Tailwind, JavaScript ja Interactivity API kontrollidega.
wordpress-render.neon Äärmuslik teema koos helistaja antud reaalajas WordPress renderdamise prooviga.

blockstudio/phpstan installimine lubab ainult põhilaienduse. Lisage olemasolevasse PHPStan konfiguratsiooni valikuline kiht:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePaths juhib teemaskannerit. PHPStan standardne excludePaths juhib eraldi PHP analüüsi.

Kanoonilise käsu säte phpstan.excludePaths failis blockstudio.json (ja selle valik --exclude) konfigureerib mõlemad kihid. Suhtelisi mustreid rakendatakse iga konfigureeritud juurkausta suhtes, seega piiravad kirjed nagu vendor/** nii PHPStan analüüsi kui ka Blockstudio projekti skannimist.

Ühte kataloogi nimetav muster, näiteks _dist/** või node_modules/**, jätab selle kataloogi välja kõikjal, kus see asub, mitte ainult teemajuure kõrval. Kaldkriipsu sisaldav muster, näiteks assets/*/docs/**, jääb juurkausta suhtes fikseerituks. Genereeritud plokivarad asuvad iga ploki sees kataloogis _dist, seega jätab kompileeritud väljundi analüüsist välja just üksikkataloogi vorm.

Kanooniline käsk

Pakett paigaldab analüüsi käivitatava failina vendor/bin/blockstudio-phpstan. See kasutab base eelseadistust, kui projekt ei vali muud, seega paketi installimine ei luba iseenesest teema ega äärmusliku teema kihte:

Shell
vendor/bin/blockstudio-phpstan --root . -- --no-progress

Eelseadistused sisaldavad laiendust juba ise. Ärge lisage kanoonilist käsku käivitavale projektile phpstan/extension-installer: paigaldaja olemasolul laaditakse extension.neon kaks korda ja PHPStan peatub enne analüüsi veaga “This file is included multiple times”.

Käsk määrab vaikimisi PHPStan mälupiiranguks 1G, et Composer hallatavad WordPress projektid ei päriks tavapärast 128M CLI ülempiiri. Selle muutmiseks andke pärast -- selgesõnaline valik PHPStan, näiteks -- --memory-limit=512M --no-progress.

Analüüsi kasutuselevõtt olemasolevas projektis

Projekti esimesel analüüsikäivitusel leitakse tavaliselt probleeme. Eelseadistuse nõrgendamise asemel looge PHPStan lähteolukorra fail ja määrake phpstan.configuration projektikonfiguratsioonile, mis selle kaasab. Nii kontrollitakse uut koodi kogu eelseadistuse ranguses, samal ajal kui registreeritud leiud ei sega:

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"
  }
}

Jätke alles rida level eelseadistuste base ja theme jaoks. Kanooniline käsk määrab neile taseme max ainult siis, kui projektikonfiguratsiooni pole kaasatud; kui taseme PHPStan pole määratud, peatub käsk veaga “No rules detected”. Eelseadistus extreme-theme määrab ise taseme max.

Suhtelised teed lähtuvad asukohast blockstudio.json. Kanooniline käsk ja hallatav commit-hook võtavad faili mõlemad kasutusele, nii et hook tõkestab uued leiud enne, kui kogu olemasolev võlg on kõrvaldatud.

Hoidke kogu projekti käsu vaikeväärtused failis blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

Suhtelisi juurkaustu arvestatakse neid deklareeriva faili asukohast. Selgesõnalised CLI väärtused asendavad vastavad JSON väärtused. Alternatiivse konfiguratsiooniallika määramiseks andke --blockstudio-json path/to/project.json. Vigane JSON, toetamata võtmed phpstan, kehtetud väärtused ja puuduva selgesõnalise allika korral lõpeb käsk deterministlikult väljumiskoodiga 2.

Valige teine eelseadistus, lisage projektikonfiguratsioon, lisage korduvad juurkaustad ja välistused või paluge PHPStan-il järgmist JSON:

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

Ümbris koostab konfiguratsiooni süsteemi ajutises kataloogis ja kustutab selle väljumisel. See ei kirjuta genereeritud konfiguratsiooni, lähteolukorra faile, hook’e ega vahemälu analüüsitavasse projekti. Soovi korral saavad kutsujad PHPStan tavapärast vahemälu selgesõnaliselt konfigureerida.

Väljumiskoodid:

  • 0, kui analüüs õnnestub
  • 1, kui PHPStan teatab diagnostikast
  • 2 vigase kasutuse, konfiguratsiooni või protsessi käivitamise korral

Hallatud sissekandekonks

Äärmusliku teema analüüsi muutmiseks hoidla commit-gate’iks lubage faili blockstudio.json seadistus, mida haldab Blockstudio:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "githooks": {
    "commit": true
  }
}

Sünkroonige see pärast sõltuvuste installimist või sätte muutmist:

Shell
vendor/bin/blockstudio-githooks sync

Käsk kirjutab genereeritud pre-commit-hook’i ja omandiõiguse kirje kataloogi Git, määrab core.hooksPath väärtuseks hallatava hook’i kataloogi ja ühendab turvaliselt varem seadistatud pre-commit-hook’i. Korduvad sünkroonimised värskendavad ainult genereeritud faili, seega on paketi uuendamine idempotentne.

Määrake commit väärtuseks false, eemaldage see või eemaldage blockstudio.json, seejärel käivitage sync, et taastada registreeritud hook’i tee ja kustutada ainult Blockstudio hallatavad failid. Võite käivitada ka:

Shell
vendor/bin/blockstudio-githooks remove

Kasutajale kuuluvaid faile ei kirjutata üle ega kustutata kunagi. Kui keegi muudab core.hooksPath pärast seda, kui Blockstudio on lubatud, säilitab eemaldamine selle uuema sätte. Genereeritud hook toetab lingitud Git väljavõtteid ja tühikuid sisaldavaid teid, tuvastades commit’i ajal aktiivse hoidla ja projekti juurkausta. See käivitab kanoonilise käsu sellest juurkaustast, nii et sama phpstan objekt juhib nii interaktiivseid käivitusi kui ka commit’e, ilma genereeritud argumente dubleerimata.

Hook käivitab ainult vendor/bin/blockstudio-phpstan. Blockstudio ei käivita vormindajat ja hook ei kirjuta projektifaile kunagi ümber. Puuduvad sõltuvused ja analüüsivead peatavad commit’i ning annavad juhised probleemi lahendamiseks.

Reaalajas WordPress renderdamine

Reaalajas kiht on teadlikult selgesõnaline. Kutsuja haldab WordPress keskkonda ja annab käsuargumentide massiivi:

Shell
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

Käsk töötab ilma shellita ja peab väljastama ühe JSON objekti:

JSON
{"ok":true}

Proov võib teatada konkreetsest tõrkest:

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

Nullist erinev väljumiskood, ajalõpp, vigane JSON ja ok: false annavad tulemuseks blockstudio.wordpress.render.

blockstudio.javascript.domContract annab teada [data-*] atribuudi valijast, mille skript edastab funktsioonile querySelector(), querySelectorAll(), closest() või matches(), kui ükski analüüsitud märgistus seda atribuuti ei sisalda. Märgistus hõlmab kõiki PHP-, Twig-, Blade- ja HTML-faile ning kõiki analüüsitavate juurte all olevaid React .tsx– ja .jsx-komponente, välja arvatud välistatud rajad. Komponente parsitakse: arvesse lähevad nii JSX atribuutide nimed kui ka objektiliteraalide stringvõtmed. Seega rahuldab valija elemendile levitatud atribuutide objekt, kuid klassinimed ja muud atribuutide väärtused mitte.

Interactivity API-kontrollid loevad samu React-komponente. Elemendi JSX data-wp-interactive nimeruum loetakse malli viiteks blockstudio.interactivity.orphan jaoks ning selles olevad data-wp-* direktiivid lahendatakse lähima ümbritseva nimeruumi või väärtuses oleva prefiksi namespace:: alusel. Staatilise stringväärtusega direktiivid, mis on kirjutatud JSX atribuudina või atribuutide objekti stringvõtmena, peavad viitama olemasolevatele poe käitlejatele ja radadele (blockstudio.interactivity.handler, blockstudio.interactivity.binding), ning poe kood ei tohi muuta atribuute ega klasse, millega need seotud on (blockstudio.interactivity.derivedState). React paotab atribuutide väärtused, seega data-wp-context komponendis ei anna teadet, ja dünaamilisi väärtusi ei kontrollita. bsui/ all olevad nimeruumid kuuluvad komplektis olevatele UI-plokkidele, mille poed tarnitakse koos Blockstudio-iga analüüsitavatest juurtest väljaspool, mistõttu need pole kunagi orvud.

Diagnostika identifikaatorid

Uued eelseadistuste diagnostikateated säilitavad stabiilsed blockstudio.* ID-d:

  • Teema struktuur: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Varad ja väljad: 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

Jõudlus

Skanner aktsepteerib tavalisi valmis katalooge, kõrvaldab juurkaustade duplikaadid, jätab vahele sõltuvuste, järgu ja vahemälu kataloogipuud, salvestab failide lugemise tulemused mällu ning sorteerib diagnostikateated deterministlikult. Hoidke juurkaustad kitsalt piiritletuna, välistage näidis- ja genereeritud kataloogipuud ning määrake suurte hoidlate jaoks failipiirang. JavaScript ja Tailwind saab teineteisest sõltumatult keelata. Reaalajas renderdamine ei käivitu, kui vastavat eelseadistust pole valitud.

Teema, JavaScript ja Tailwind diagnostikateated edastatakse PHPStan tulemuste vahemälu kaudu. Kui muudate ainult block.json või skripti, võib soojendatud vahemälu kuvada eelmise tulemuse. Selliste muudatuste kontrollimisel jätke vahemälu vahele, andes pärast -- valiku --debug.

Kodeerimisagentide projektileping

Pakett paigaldab kolmanda käivitatava faili, vendor/bin/blockstudio-agents. See kirjutab AGENTS.md, mis kirjeldab projekti, milles see töötab; seda vajab kodeerimisagent enne mis tahes muudatuste tegemist: mida projekt loob, millised Blockstudio funktsioonid on lubatud, mida analüüs tagasi lükkab ja millised käsud kehtivad.

Shell
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Väljundis pole midagi fikseeritud malli järgi loodud. Iga rida pärineb ühest kolmest allikast:

  • Projekti enda failid. style.css päisega teema, plokid ja failipõhised lehed annavad teistsuguse dokumendi kui plugin, mis registreerib ainult plokke. Loendused, kataloogid, plokkide nimeruumid ja mallikeeled vastavad sellele, mida skanner tegelikult leidis, kasutades samu juurkaustu ja välistusi nagu analüüs.
  • blockstudio.json. Kirjeldatakse ainult lubatud funktsioone ja nende seadistatud väärtusi: plokisiltide eesliiteid ja nimeruume, mille kaudu need lahendatakse, Tailwind, kaasasolevat UI, redaktori varade lähtestamist, vahemälu teed, jõudlusprofiili, staatilist eeltöötlust ja selle dünaamilisi teid, teema vaikeväärtusi, sisusünkroonimist ja commit-hook’i.
  • Valitud phpstan.preset. Õigsuse jaotis loetakse eelseadistuse failidest kihtide kaupa, nii et seal on täpselt loetletud eelseadistuse registreeritud reeglid. Tasemel base kirjeldatakse skeemi, mallide, hook’ide ja seadete reegleid. Tasemel extreme-theme kirjeldatakse ka teema struktuuri reegleid, rangeid PHPStan lippe, ohtlikku PHP, väljundi paomärke, Tailwind ja JavaScript. Kui eelseadistusele lisatakse reegel, lisatakse see ka genereeritud dokumenti.

Käskude jaotis järgib sama põhimõtet. wp bs prerender status kuvatakse staatilise eeltöötluse lubamisel, vendor/bin/blockstudio-githooks sync siis, kui määratud on githooks.commit, ja wp bs db schemas siis, kui projektil on tegelikult db.php.

Valik Käitumine
--root <path> Projekti juurkaust (vaikimisi praegune kataloog)
--config <path> blockstudio.json tee (vaikimisi <root>/blockstudio.json)
--output <path> Lepingu tee (vaikimisi <root>/AGENTS.md)
--stdout Lepingu kirjutamise asemel kuva see
--check Välju koodiga 1, kui kettal olev leping pole ajakohane
--force Asenda fail, mida Blockstudio ei halda

--check muudab lepingu CI-kontrollväravaks, nagu commit-hook muudab analüüsi kontrollväravaks:

Shell
vendor/bin/blockstudio-agents --check

Omandiõigus

Genereeritud fail sisaldab samasugust markerit nagu hallatav commit-hook ja sellele kehtib sama reegel: Blockstudio ei asenda kunagi faili, mida see ise pole kirjutanud. Kui AGENTS.md oli olemas juba enne käsu käivitamist või autor kirjutas selle käsitsi, keeldutakse selle muutmisest väljumiskoodiga 2 ja fail jäetakse puutumata, kuni antakse --force.

Taastamine on ohutu. Fail lõpeb märkmete jaotisega ja selle markerite vahele jäävad baidid säilitatakse igal taastamisel:

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

Väljumiskoodid on 0, kui leping kirjutatakse, on ajakohane või prinditakse; 1, kui --check leiab aegunud lepingu; ja 2 kasutus-, konfiguratsiooni- või failisüsteemi vigade korral.

Väljatüüpide kujud

Laiendus seostab iga Blockstudio väljatüübi konkreetse PHP tüübiga:

Väljatüüp PHP tüüp
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (üksik) string|int
select, checkbox (mitu) 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 (üksik) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (mitu) list<array{id: int, url: string, ...}>
group Nimega rühmad kasutavad allkriipsuga prefikseid; anonüümsed rühmad tasandatakse vanemulatuse sisse
repeater list<array{...child fields...}>
tabs Tasandatakse vanemulatuse sisse

API tüübitüved

Laiendusega on kaasas täieliku Blockstudio avaliku API tüübitüved:

  • 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()

Need võimaldavad automaattäite ja tüübikontrolli, ilma et Blockstudio plugina lähtekood peaks teie arvutis olemas olema.

Nõuded

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (soovitatav automaatseks tuvastamiseks)

Pakett paigaldab BC Mathi ühilduvuskihi automaatselt. Seega on omaalgne ext-bcmath valikuline, sealhulgas värskelt genereeritud teemade puhul, mis lubavad JavaScript kontrollid teema või äärmusliku eelseadistuse kaudu.