Pereiti prie turinio

PHPStan

Plėtinys blockstudio/phpstan suteikia statinės analizės galimybes Blockstudio projektams. Jis analizės metu tikrina blokų šablonus, schemų failus, nustatymų kelius ir kabliukų pavadinimus, taip aptikdamas klaidas dar prieš joms pasiekiant vykdymo aplinką.

Diegimas

Shell
composer require --dev blockstudio/phpstan

7.7 versijos šablonų tipizavimui ir išplėstiniams blokų žymų patikrinimams reikia blockstudio/phpstan 0.1.9 ar naujesnės versijos ir PHPStan 2.1.47 ar naujesnės versijos. Paketą atnaujinkite atskirai nuo papildinio:

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

Plėtinys aptinkamas automatiškai per PHPStan plėtinių diegimo programą. Nereikia jokios rankinės konfigūracijos.

Ką tikrina

Prieiga prie šablono laukų

Kai failas PHP yra šalia block.json, plėtinys tikrina kiekvieną prieigą $a['key'] pagal deklaruotus bloko atributus.

PHP
<?php

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

Plėtinys žino, kad Blockstudio apibrėžia $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview ir salos kintamuosius prieš įtraukdamas šabloną, todėl tiesioginės prieigos, tokios kaip $a['title'], nelaikomos galimai neapibrėžtomis, o $a tipas nustatomas pagal šalia šablono esančią block.json. Ši struktūra išlieka siaurinant tipus, todėl $a['label'] ?? '', isset( $a['cta']['target'] ) ir $a['cta']['title'] !== null išlaiko deklaruotus laukų tipus; jei šablonas priskiria reikšmę pačiam $a, jam priskirtas tipas išlieka. Nedėkite /** @var array<string, mixed> $a */ dokumentacijos bloko: jis pakeičia šią struktūrą atviru masyvu.

Laukų raktams taikomos Blockstudio vykdymo aplinkos išlyginimo taisyklės. tabs ir anoniminiai group konteineriai be id skirti tik pateikimui, todėl jų antriniai laukai lieka pirminėje srityje. Pavadinta grupė prie antrinių laukų raktų prideda grupės ID:

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

Pakartotinai naudojami pasirinktiniai laukai

Prieš tikrinant šablonų raktus ir masyvų struktūras, išplečiamos failuose apibrėžtos custom/* nuorodos. Plėtinys nuskaito atitinkamą field.json ir taiko tas pačias idStructure, overrides, įdėtinių nuorodų, grupių, skirtukų ir kartotuvų taisykles kaip Blockstudio:

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

Gauti šablonų raktai yra title ir hero_description. Jie atpažįstami srityse PHP, Twig, Blade, blokų žymose ir nustatomose atributų struktūrose.

Trūkstant, esant dviprasmiškam, netinkamam ar cikliniam failuose apibrėžtam aprašui, pateikiama konkreti blockstudio.customField.* klaida. To bloko priklausomų raktų patikros praleidžiamos, kad vienas neišspręstas aprašas nesukeltų papildomos klaidų dėl nežinomų laukų bangos.

Statinė analizė negali nustatyti aprašų, registruojamų tik vykdymo metu per filtrą blockstudio/fields PHP. Jei laukui reikia statiškai tikrinamų šablonų raktų, naudokite aprašą field.json.

Prieiga prie Twig šablonų

Twig šablonai nuskaitomi automatiškai. Anotacijų nereikia.

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

Prieiga prie Blade šablonų

Blade šablonai nuskaitomi tokiu pačiu būdu.

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

Blokų žymų tikrinimas

Blokų žymos tikrinamos ten, kur Blockstudio jas nuskaito: <bs:> ir <block> žymose, blockTags.prefixes sukonfigūruotose prefiksų žymose (pavyzdžiui, <acme-card>, nustatomose pagal vardų sričių tvarką, kaip ir vykdymo aplinkoje) ir alternatyviose žymose; šablonuose PHP, Twig bei Blade ir puslapių išdėstymuose. Taip pat tikrinami puslapių šaltiniai, esantys žemiau pages/ (index.php, index.html, index.twig, index.blade.php), įskaitant HTML elementus, kuriuos projektas susieja su blokais. Kai įjungta ui.enabled, atpažįstami ir komplekte esantys UI blokai.

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

Atributas priimamas, jei blokas jį deklaruoja kaip lauką (įskaitant pasirinktinius laukus ir laukus, kuriuos bloko tipo laukas perduoda per savo idStructure) arba jei Blockstudio perduoda jį pagrindiniam bloko elementui: data-*, aria-*, id, style, role, title, lang, dir, hidden ir tabindex. Šablonuose perduodami visi html-* atributai; puslapių šaltiniuose html- prefiksas nurodo tik vieną iš perduodamų atributų. Pranešama apie visus kitus atributus, ypač nedeklaruotą class, nes Blockstudio jį išsaugo, bet niekada neatvaizduoja.

Vykdymo aplinka registruoja elementų susiejimus ir žymų alternatyvas filtruose PHP, kurių statinė analizė negali įvertinti, todėl analizė juos nuskaito iš blockstudio.json. scanPhp taip pat tikrina žymas kituose projekto PHP failuose, pavyzdžiui, komponentų žymėjime moduliuose, tačiau nepraneša apie ten esančius nežinomus blokus:

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

Elementas susiejamas su bloko pavadinimu arba taisyklių seka, tikrinama eilės tvarka: pritaikoma pirma taisyklė, kurios atributą turi elementas, o paprastas bloko pavadinimas visada atitinka. Nesusieti projekto elementai išlaiko pagrindinį bloką ir nėra tikrinami. Diagnostikoje naudojami blockstudio.blockTag.unknown, blockstudio.blockTag.attribute ir blockstudio.blockTag.class.

Duomenų bazės įrašų tipizavimas

Db::get() pateikia tipizuotą egzempliorių pagal db.php schemą. Įrašų struktūros nustatomos automatiškai.

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

Privalomi laukai nėra nuliniai. Pasirinktiniai laukai yra type|null. Laukas id (int) visada pateikiamas. Toks pats tipizavimas taikomas PHP savitajai Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field kūrimo sintaksei.

Nustatymų kelių tikrinimas

Settings::get() keliai tikrinami pagal žinomą nustatymų schemą.

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

Kabliukų pavadinimų tikrinimas

Tikrinami Blockstudio filtrų ir veiksmų kabliukų pavadinimai.

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

Dinaminiai nustatymų kabliukai, tokie kaip blockstudio/settings/tailwind/enabled, visada leidžiami. Ne blockstudio kabliukai ignoruojami.

Schemos tikrinimas

Plėtinys tikrina kiekvieną projekto Blockstudio schemos failą.

block.json:

  • Trūksta name lauko
  • Trūksta lauko type
  • Trūksta id laukams, kuriems jis reikalingas
  • Nežinomi laukų tipai
  • Lauko savybės, kurių laukų tipas nepriima, pavyzdžiui, "translat" vietoj "translate"; pasiūloma artimiausia žinoma savybė
  • select/radio/checkbox be options arba populate
  • Pasikartojantys laukų ID
  • tabs laukas kartotuvo viduje – tiesiogiai arba grupėje be id
  • Netinkamos pluginDependencies deklaracijos

Konteinerių laukuose, pavyzdžiui, group ir tabs, taip pat custom/* laukų nuorodose, galima nenurodyti id, jei jos tik išplečia ar apgaubia kitus laukus.

Laukų savybės tikrinamos pagal savybes, kurias kiekvienam integruotam lauko tipui deklaruoja schemas/block.json, ir savybes, kurias priima visi laukai. custom/* nuorodoms skirtos savybės ir projekte apibrėžti vardų srities lauko tipai į šį tikrinimą neįtraukiami. Esami lauko tipų ir pasirinktinių nuorodų tikrinimai lieka galioti. Identifikatoriai: blockstudio.blockJson.property ir blockstudio.fieldJson.property.

Tikrinami savybių pavadinimai, o ne vien jų reikšmės: minimized galioja kartotiniam laukui, bet apie jį pranešama teksto lauke. Įskiepio veikimas vykdymo metu nesikeičia. Jei projekte prie integruotų laukų sąmoningai pridedami savi metaduomenys, slopinkite tik šiuos radinius, neišjungdami kitų struktūros patikrų:

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

Integruoti laukai daugkartinio naudojimo field.json viduje vis tiek tikrinami, net jei custom/* nuoroda turi savų apvalkalo parinkčių. Plėtinio failai nepatenka į šios savybių pavadinimų diagnostikos apimtį; plėtiniui būdingos set taisyklės lieka galiojančios.

field.json (pakartotinai naudojami pasirinktiniai laukai):

  • Trūksta name
  • Trūksta arba tuščias attributes
  • Netinkami atributų objektai arba trūksta lauko type
  • Trūksta id reikšmės laukams, kuriems jis būtinas
  • Nežinomi laukų tipai
  • Lauko savybės, kurių lauko tipas nepriima
  • tabs laukas kartotiniame lauke tiesiogiai arba grupėje be id
  • Trūksta įdėtinių custom/* nuorodų arba jos dviprasmės, netinkamos ar ciklinės

Plėtinys JSON (blokų plėtiniai extensions/):

  • Trūksta name (paskirties bloko)
  • Trūksta rakto blockstudio
  • Trūksta rakto blockstudio.extend

page.json (failais pagrįsti puslapiai):

  • Trūksta title
  • Trūksta slug
  • Netinkamos postStatus reikšmės

db.php:

  • Trūksta masyvo fields
  • Netinkami laukų tipai
  • Palaikomi ir senieji masyvai, ir Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Netinkami HTTP metodai
  • Neteisinga public reikšmė (turi būti true, false arba 'open')
  • Palaikomi ir senieji masyvai, ir atributais pažymėtų objektų grąžinamos reikšmės

cron.php:

  • Trūksta schedule sukonfigūruotose užduotyse
  • Trūksta callback sukonfigūruotose užduotyse
  • Palaikomi ir senieji masyvai, ir grąžinami objektai su atributais

blockstudio.json:

  • Trumpieji loginiai įrašai, pvz., "tailwind": true (būtina naudoti įdėtinio objekto formatą {"enabled": true, "config": ""})

Konfigūracija

Plėtinys pagal numatytuosius nustatymus aptinka Blockstudio failus analizuojamame projekte. Jei projekte naudojami blokai arba pakartotinai naudojami laukai iš bibliotekos, esančios už projekto šakninio katalogo ribų, pridėkite bibliotekos kelią prie blockstudioScanRoots. Kelias skenuojamas ieškant ir block.json, ir field.json apibrėžčių, todėl išorinių blokų gairės ir jų tinkinti laukai gali būti tikrinami kartu.

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

Norėdami ignoruoti failus, naudokite standartinę excludePaths konfigūraciją, skirtą PHPStan.

Analizės išankstiniai nustatymai

Automatiškai aptinkamas plėtinys išlieka suderinamumui saugiu pagrindu. Blockstudio 7.6 prideda pasirenkamus sluoksnius nekeisdama esamų projektų:

Išankstinis nustatymas Veikimas
base.neon Esamos schemos, šablono, kabliukų, nustatymų ir API analizė.
theme.neon Pagrindas ir WordPress temų šakniniai katalogai, stilių antraštės, Blockstudio ištekliai, selektorių aprėpties apribojimas, laukų numatytosios reikšmės ir kartotuvo ribos.
extreme-theme.neon Tema ir PHPStan max, nesaugus PHP, išvesties ekranavimas, Tailwind, JavaScript ir Interactivity API patikros.
wordpress-render.neon Ekstremali tema ir skambintojo pateiktas tiesioginis WordPress atvaizdavimo patikrinimas.

Įdiegus blockstudio/phpstan įjungiamas tik pagrindinis plėtinys. Įtraukite pasirenkamą sluoksnį į esamą PHPStan konfigūraciją:

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

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

blockstudioThemeExcludePaths valdo temų skaitytuvą. Standartinis excludePaths nustatymas, skirtas PHPStan, atskirai valdo PHP analizę.

Kanoninės komandos nustatymas phpstan.excludePaths faile blockstudio.json (ir jos parinktis --exclude) konfigūruoja abu sluoksnius. Santykiniai šablonai sprendžiami pagal kiekvieną sukonfigūruotą šakninį katalogą, todėl tokie įrašai kaip vendor/** apriboja PHPStan analizę ir Blockstudio projekto skenavimą.

Vieną katalogą nurodantis šablonas, pvz., _dist/** arba node_modules/**, neįtraukia to katalogo, kad ir kur jis būtų, o ne tik šalia temos šakninio katalogo. Šablonas su pasviruoju brūkšniu, pvz., assets/*/docs/**, išlieka susietas su šakniniu katalogu. Sugeneruoti blokų ištekliai laikomi kiekvieno bloko _dist kataloge, todėl kompiliuotą išvestį nuo analizės apsaugo vieno katalogo forma.

Kanoninė komanda

Paketas įdiegia vendor/bin/blockstudio-phpstan kaip analizės vykdomąjį failą. Jei projektas nepasirenka kito nustatymo, vykdoma base išankstinė nuostata, todėl vien paketo įdiegimas savaime neįjungia temos ar ekstremalios temos sluoksnių:

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

Patys išankstiniai nustatymai įtraukia plėtinį. Nepridėkite phpstan/extension-installer prie projekto, kuriame vykdoma kanoninė komanda: įdiegus paketą, extension.neon įkeliamas du kartus, o PHPStan sustoja su pranešimu „Šis failas įtrauktas kelis kartus“ dar nepradėjęs analizės.

Pagal numatytuosius nustatymus komanda nustato PHPStan į 1G atminties limitą, kad Composer valdomi WordPress projektai nepaveldėtų įprastos 128M CLI ribos. Norėdami jį pakeisti, po -- perduokite aiškią parinktį PHPStan, pvz., -- --memory-limit=512M --no-progress.

Analizės pritaikymas esamame projekte

Pirmą kartą analizuojant projektą paprastai aptinkama problemų. Užuot sumažinę išankstinio nustatymo griežtumą, sukurkite PHPStan bazinį failą ir nurodykite phpstan.configuration projekto konfigūraciją, kurioje jis įtrauktas. Naujasis kodas ir toliau tikrinamas pagal visą išankstinį nustatymą, o užfiksuotos problemos netrukdo:

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

Palikite eilutę level naudodami base ir theme išankstinius nustatymus. Kanoninė komanda jiems nustato tik max lygį, kai neįtraukta jokia projekto konfigūracija; jei lygis nenustatytas, PHPStan sustoja su pranešimu „Taisyklių nerasta“. extreme-theme išankstinis nustatymas pats nustato max lygį.

Santykiniai keliai sprendžiami pagal blockstudio.json. Kanoninė komanda ir valdomas pakeitimų patvirtinimo kabliukas aptinka šį failą, todėl kabliukas blokuoja naujas problemas, bet pirmiausia nereikia pašalinti visų senų.

Visos projektui skirtos numatytosios komandų reikšmės turi būti faile blockstudio.json:

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

Santykiniai šakniniai katalogai nustatomi pagal juos deklaruojantį failą. Aiškios CLI reikšmės pakeičia atitinkamas JSON reikšmes. Norėdami nurodyti kitą konfigūracijos šaltinį, perduokite --blockstudio-json path/to/project.json. Netaisyklingas JSON, nepalaikomi phpstan raktai, netinkamos reikšmės ir nurodyto šaltinio nebuvimas visada pateikia klaidą su išėjimo kodu 2.

Pasirinkite kitą išankstinį nustatymą, įtraukite projekto konfigūraciją, pridėkite kartotinius šakninius katalogus ir išimtis arba paprašykite PHPStan JSON:

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

Apvalkalas sudaro konfigūraciją laikinojoje sistemos direktorijoje ir ištrina ją baigęs darbą. Jis niekada neįrašo sugeneruotos konfigūracijos, bazinių failų, kabliukų ar podėlių į analizuojamą projektą. Vis dėlto skambintojai gali aiškiai sukonfigūruoti įprastą PHPStan podėlį.

Išėjimo kodai:

  • 0, jei analizė sėkminga
  • 1, jei PHPStan pateikia diagnostikos pranešimų
  • 2, jei netinkamai naudojama, sukonfigūruota arba vykdomas procesas

Valdomas pateikimo pakeitimų kabliukas

Kad ekstremalios temos analizė taptų saugyklos pakeitimų patvirtinimo patikra, įjunkite Blockstudio valdomą kabliuką faile blockstudio.json:

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

Sinchronizuokite jį įdiegę priklausomybes arba pakeitę nustatymą:

Shell
vendor/bin/blockstudio-githooks sync

Komanda įrašo sugeneruotą išankstinio patvirtinimo kabliuką ir nuosavybės įrašą į bendrą Git katalogą, nustato core.hooksPath į valdomo kabliuko katalogą ir saugiai susieja anksčiau sukonfigūruotą išankstinio patvirtinimo kabliuką. Kartotinė sinchronizacija atnaujina tik sugeneruotą failą, todėl paketo naujinimus galima taikyti pakartotinai be šalutinių pakeitimų.

Nustatykite commit į false, pašalinkite jį arba pašalinkite blockstudio.json, tada paleiskite sync, kad būtų atkurtas įrašytas kabliuko kelias ir ištrinti tik Blockstudio priklausantys failai. Taip pat galite paleisti:

Shell
vendor/bin/blockstudio-githooks remove

Naudotojams priklausantys failai niekada neperrašomi ir neištrinami. Jei kas nors pakeičia core.hooksPath po to, kai įjungiamas Blockstudio, šalinant išsaugomas naujesnis nustatymas. Sugeneruotas kabliukas palaiko susietus Git darbinius katalogus ir tarpus keliuose, nes pakeitimų patvirtinimo metu nustato aktyvią saugyklą ir projekto šakninį katalogą. Jis vykdo kanoninę komandą iš to šakninio katalogo, todėl tas pats phpstan objektas valdo interaktyvius paleidimus ir pakeitimų patvirtinimus, o sugeneruotų argumentų dubliuoti nereikia.

Kabliukas vykdo tik vendor/bin/blockstudio-phpstan. Blockstudio neformatuoja kodo ir kabliukas niekada neperrašo projekto failų. Trūkstamos priklausomybės ir analizės klaidos blokuoja pakeitimų patvirtinimą, pateikdamos aiškų klaidos pranešimą.

Tiesioginis WordPress atvaizdavimas

Tiesioginis sluoksnis įjungiamas aiškiai. Skambintojas valdo WordPress aplinką ir pateikia argv masyvą:

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

Komanda vykdoma be apvalkalo ir turi išvesti vieną JSON objektą:

JSON
{"ok":true}

Patikra gali pateikti konkrečią klaidą:

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

Nulinio kodo neatitinkantys išėjimai, skirtojo laiko pabaiga, netaisyklingas JSON ir ok: false pateikia blockstudio.wordpress.render.

blockstudio.javascript.domContract praneša apie [data-*] atributo selektorių, kurį scenarijus perduoda querySelector(), querySelectorAll(), closest() arba matches(), kai nė viename analizuojamame žymėjime šio atributo nėra. Žymėjimą sudaro visi PHP, Twig, Blade ir HTML failai bei visi React .tsx ir .jsx komponentai analizuojamose šakninėse direktorijose, išskyrus atmestus kelius. Komponentai išskaidomi: JSX atributo pavadinimai įskaitomi, kaip ir objektų literatų eilučių raktai, todėl elementui pritaikytas atributų objektas atitinka selektorių, o klasių pavadinimai ir kitos atributų reikšmės – ne.

Interaktyvumo API patikros skaito tuos pačius React komponentus. JSX elemente esanti data-wp-interactive vardų sritis laikoma šablono nuoroda, skirta blockstudio.interactivity.orphan, o joje esančios data-wp-* direktyvos susiejamos su artimiausia išorine vardų sritimi arba su namespace:: prefiksu reikšmėje. Direktyvos su statine eilutės reikšme, nurodytos kaip JSX atributas arba kaip atributų objekto eilutės raktas, turi nurodyti esamas saugyklos apdorojimo funkcijas ir kelius (blockstudio.interactivity.handler, blockstudio.interactivity.binding), o saugyklos kodas negali keisti atributų ir klasių, su kuriomis jos susietos (blockstudio.interactivity.derivedState). React išvengia atributų reikšmių, todėl apie data-wp-context komponente nepranešama, o dinaminės reikšmės netikrinamos. Vardų sritys po bsui/ priklauso susietiems UI blokams, kurių saugyklos pateikiamos kartu su Blockstudio už analizuojamų šakninių direktorijų ribų, todėl jos niekada nelaikomos našlaitėmis.

Diagnostikos identifikatoriai

Naujos išankstinių nustatymų diagnostikos išlaiko stabilius blockstudio.* ID:

  • Temos struktūra: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Ištekliai ir laukai: blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP: blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind: blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript: blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • Interactivity: blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

Našumas

Skaitytuvas priima įprastus katalogus, pašalina pasikartojančius šakninius katalogus, praleidžia priklausomybių, kūrimo ir podėlių katalogų medžius, podėliuoja failų turinį atmintyje ir nuosekliai rūšiuoja diagnostikos pranešimus. Rinkitės siauras šaknines vietas, neįtraukite testinių ir sugeneruotų katalogų, o didelėse saugyklose nustatykite failų limitą. JavaScript ir Tailwind galima išjungti atskirai. Tiesioginis atvaizdavimas vykdomas tik pasirinkus atitinkamą išankstinį nustatymą.

Temos, JavaScript ir Tailwind diagnostikos pateikiamos per PHPStan rezultatų podėlį. Pakeitus tik block.json arba skriptą, podėlyje gali būti pateiktas ankstesnis rezultatas. Norėdami apeiti podėlį ir patikrinti tokius pakeitimus, po -- perduokite --debug.

Projektui taikomos taisyklės programavimo agentams

Paketas įdiegia trečią vykdomąjį failą – vendor/bin/blockstudio-agents. Jis sugeneruoja AGENTS.md, kuriame aprašomas projektas, kuriame veikia. Tokią informaciją kodavimo agentui reikia žinoti prieš keičiant bet ką: ką kuria projektas, kurios Blockstudio funkcijos įjungtos, ką analizė atmes ir kurios komandos taikomos.

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

Išvestis nėra sudaryta iš nekintamo šablono. Kiekviena eilutė gaunama iš vieno iš trijų šaltinių:

  • Paties projekto failai. Tema su style.css antrašte, blokais ir iš failų sudarytais puslapiais sukuria kitokį dokumentą nei papildinys, registruojantis tik blokus. Skaičiai, katalogai, blokų vardų sritys ir šablonų kalbos atspindi tai, ką iš tikrųjų aptiko skaitytuvas, naudodamas tuos pačius šakninius katalogus ir išimtis kaip analizė.
  • blockstudio.json. Aprašomos tik įjungtos funkcijos ir jų sukonfigūruotos reikšmės: blokų gairių priešdėliai ir vardų sritys, per kurias jos sprendžiamos, Tailwind, susietas UI, redaktoriaus išteklių nustatymas iš naujo, podėlio kelias, našumo profilis, statinis išankstinis atvaizdavimas ir jo dinaminiai keliai, numatytieji temos nustatymai, Content Sync ir pakeitimų patvirtinimo kabliukas.
  • Pasirinktas phpstan.preset. Teisingumo skyrius skaitomas iš pačių išankstinių nustatymų failų, sluoksnis po sluoksnio, todėl jame išvardytos tiksliai tos taisyklės, kurias registruoja tas nustatymas. base aprašomos schemos, šablono, kabliukų ir nustatymų taisyklės. extreme-theme taip pat aprašomos temos struktūros taisyklės, griežtos PHPStan vėliavėlės, nesaugus PHP, išvesties ekranavimas, Tailwind ir JavaScript. Kartu su nauja taisykle atnaujinamas ir sugeneruotas dokumentas.

Komandų skyrius sudaromas pagal tą patį principą. wp bs prerender status rodomas įjungus statinį išankstinį atvaizdavimą, vendor/bin/blockstudio-githooks sync – nustačius githooks.commit, o wp bs db schemas – jei projekte iš tiesų yra db.php.

Parinktis Veikimas
--root <path> Projekto šakninis katalogas (numatytasis: dabartinis katalogas)
--config <path> blockstudio.json kelias (numatytasis: <root>/blockstudio.json)
--output <path> Taisyklių rinkinio kelias (numatytasis: <root>/AGENTS.md)
--stdout Išveda taisyklių rinkinį jo neįrašydama
--check Grąžina išėjimo kodą 1, jei diske esantis taisyklių rinkinys pasenęs
--force Pakeičia failą, kurio nevaldo Blockstudio

--check paverčia taisyklių rinkinį CI patikra, kaip pakeitimų patvirtinimo kabliukas paverčia tokia patikra analizę:

Shell
vendor/bin/blockstudio-agents --check

Nuosavybė

Sugeneruotame faile įrašoma tokio pat tipo žyma kaip ir valdomame pakeitimų patvirtinimo kabliuke, todėl taikoma ta pati taisyklė: Blockstudio niekada nepakeičia failo, kurio pati nesukūrė. Jei AGENTS.md buvo sukurtas prieš komandą arba rankiniu būdu autoriaus, jis atmetamas su išėjimo kodu 2 ir paliekamas nepakeistas, kol nepateikiama --force.

Atkurti failą saugu. Jis baigiasi pastabų sritimi, o baitai tarp jos žymų išsaugomi po kiekvieno generavimo:

Markdown
## Project notes

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

Kai taisyklių rinkinys įrašomas, yra aktualus arba išvedamas, grąžinamas išėjimo kodas 0; kai --check aptinka pasenusį taisyklių rinkinį – 1; naudojimo, konfigūracijos ar failų sistemos klaidų atveju – 2.

Laukų tipų formos

Plėtinys kiekvieną Blockstudio lauko tipą susieja su konkrečiu PHP tipu:

Lauko tipas PHP tipas
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (vienas) string|int
select, checkbox (keli) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files (vienas) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (keli) list<array{id: int, url: string, ...}>
group Pavadintos grupės naudoja pabraukimo brūkšnio prefiksus; anoniminės grupės išskleidžiamos į pirminę sritį
repeater list<array{...child fields...}>
tabs Išskleidžiama į pirminę sritį

API aprašai be realizacijos

Plėtinys pateikiamas su visos Blockstudio viešosios API sistemos tipų aprašais:

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

Jie suteikia automatinį užbaigimą ir tipų tikrinimą, todėl Blockstudio papildinio šaltinio kodo kompiuteryje turėti nereikia.

Reikalavimai

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (rekomenduojama automatiniam aptikimui)

Paketas automatiškai įdiegia BC Math suderinamumo teikėją. Todėl savoji ext-bcmath pasirenkama, taip pat ir naujoms sugeneruotoms temoms, kuriose temos arba ekstremaliame išankstiniame nustatyme įjungtos JavaScript patikros.