Preskočiť na obsah

PHPStan

Rozšírenie blockstudio/phpstan prináša statickú analýzu do projektov Blockstudio. Pri analýze overuje šablóny blokov, súbory schém, cesty k nastaveniam a názvy hookov, takže chyby odhalí ešte pred spustením.

Inštalácia

Shell
composer require --dev blockstudio/phpstan

Typovanie šablón vo verzii 7.7 a rozšírené kontroly značiek blokov vyžadujú verziu blockstudio/phpstan 0.1.9 alebo novšiu a verziu PHPStan 2.1.47 alebo novšiu. Aktualizujte balík oddelene od zásuvného modulu:

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

Rozšírenie sa automaticky objaví prostredníctvom inštalátora rozšírení PHPStan. Nie je potrebná žiadna ručná konfigurácia.

Čo kontroluje

Prístup k poliam šablóny

Keď sa súbor PHP nachádza vedľa súboru block.json, rozšírenie overuje každý prístup $a['key'] podľa deklarovaných atribútov bloku.

PHP
<?php

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

Rozšírenie vie, že Blockstudio definuje $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview a premenné island ešte pred vložením šablóny. Priame čítania, ako napríklad $a['title'], preto neoznačí ako potenciálne nedefinované a typ premennej $a odvodí z block.json vedľa šablóny. Tvar zostane zachovaný aj po zúžení typu, takže $a['label'] ?? '', isset( $a['cta']['target'] ) a $a['cta']['title'] !== null si ponechajú deklarované typy polí; šablóna, ktorá priradí hodnotu samotnej premennej $a, si zachová priradený typ. Nepridávajte blok dokumentácie /** @var array<string, mixed> $a */: nahradí tento tvar otvoreným poľom.

Kľúče polí sa riadia pravidlami Blockstudio na zlučovanie za behu. tabs a anonymné kontajnery group bez atribútu id slúžia iba na prezentáciu, takže ich podradené polia zostávajú v nadradenom rozsahu. Názov skupiny sa pridáva pred kľúče jej podradených polí:

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

Opätovne použiteľné vlastné polia

Odkazy custom/* založené na súboroch sa rozbalia ešte pred kontrolou kľúčov šablóny a tvarov polí. Rozšírenie načíta zodpovedajúce field.json a uplatní rovnaké pravidlá pre idStructure, overrides, vnorené odkazy, skupiny, karty a opakovače ako 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" }
        }
      }
    ]
  }
}

Výsledné kľúče šablóny sú title a hero_description. Rozpoznávajú sa v PHP, Twig, Blade, značkách blokov a odvodených tvaroch atribútov.

Chýbajúce, nejednoznačné, neplatné alebo cyklické definície založené na súboroch vyvolajú konkrétnu chybu blockstudio.customField.*. Kontroly závislých kľúčov sa pre tento blok preskočia, aby jedno nevyriešené určenie neviedlo k ďalším chybám o neznámych poliach.

Definície registrované iba za behu prostredníctvom filtra blockstudio/fields PHP nemožno odvodiť statickou analýzou. Ak má pole prispievať k staticky kontrolovaným kľúčom šablóny, použite definíciu field.json.

Prístup k šablónam Twig

Šablóny Twig sa skenujú automaticky. Anotácia nie je potrebná.

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

Prístup k šablónam Blade

Šablóny Blade sa skenujú rovnakým spôsobom.

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

Overovanie značiek blokov

Značky blokov sa overujú na miestach, kde ich číta Blockstudio: značky <bs:> a <block>, značky s predponou nakonfigurovanou v blockTags.prefixes (napríklad <acme-card>, ktorá sa rozpoznáva v poradí menných priestorov rovnako ako za behu) a značky aliasov v šablónach blokov PHP, Twig a Blade, ako aj v rozloženiach stránok. Kontrolujú sa aj zdroje stránok pod pages/ (index.php, index.html, index.twig, index.blade.php) vrátane prvkov HTML, ktoré projekt mapuje na bloky. Pribalené bloky UI sú známe, keď je zapnuté ui.enabled.

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

Atribút sa akceptuje, ak ho blok deklaruje ako pole (vrátane vlastných polí a polí, ktoré typované pole bloku sprostredkúva cez svoje idStructure), alebo ak ho Blockstudio sprostredkúva koreňovému prvku bloku: data-*, aria-*, id, style, role, title, lang, dir, hidden a tabindex. V šablónach sa prenáša každý atribút html-*; v zdrojoch stránok predpona html- označuje iba jeden zo sprostredkovaných atribútov. Nahlási sa všetko ostatné, najmä nedeklarovaný atribút class, pretože Blockstudio ho ukladá, ale nikdy nevykreslí.

Runtime registruje mapovania prvkov a aliasy značiek vo filtroch PHP, ktoré statická analýza nedokáže vyhodnotiť, preto ich analýza načíta z blockstudio.json. scanPhp kontroluje značky aj v ostatných PHP projektu, napríklad značky komponentov v moduloch, bez toho, aby tam hlásil neznáme bloky:

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

Prvok sa mapuje na názov bloku alebo na pravidlá skúšané v poradí: vyhrá prvé pravidlo, ktorého atribút prvok obsahuje, pričom jednoduchý názov bloku sa vždy zhoduje. Prvky, ktoré projekt nemapuje, si zachovajú svoj základný blok a nekontrolujú sa. Diagnostické správy používajú blockstudio.blockTag.unknown, blockstudio.blockTag.attribute a blockstudio.blockTag.class.

Typovanie záznamov databázy

Db::get() vracia typovanú inštanciu založenú na schéme db.php. Tvary záznamov sa odvodzujú automaticky.

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

Povinné polia nemôžu mať hodnotu null. Voliteľné polia sú type|null. Pole typu id (int) je vždy prítomné. Rovnaké typovanie funguje aj v syntaxi nástroja na tvorbu PHP-native Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Validácia ciest nastavení

Cesty Settings::get() sa kontrolujú podľa známej schémy nastavení.

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

Validácia názvov hákov

Overujú sa názvy filtrov Blockstudio a hookov akcií.

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

Dynamické hooky nastavení, ako napríklad blockstudio/settings/tailwind/enabled, sú vždy povolené. Hooky nesúvisiace s blockstudio sa ignorujú.

Validácia schém

Rozšírenie overuje každý súbor schémy Blockstudio v projekte.

block.json:

  • Chýba pole name
  • Chýba pole type
  • Chýba id v poli hodnoty, ktoré ho vyžaduje
  • Neznáme typy polí
  • Vlastnosti poľa, ktoré daný typ nepodporuje, napríklad "translat" namiesto "translate"; navrhne sa najbližšia známa vlastnosť
  • select/radio/checkbox bez options alebo populate
  • Duplicitné ID polí
  • Pole tabs vo vnútri opakovača, priamo alebo v skupine bez id
  • Neplatné deklarácie pluginDependencies

Kontajnerové polia, ako sú group a tabs, ako aj odkazy na polia custom/*, môžu vynechať id, ak iba rozbaľujú alebo obaľujú iné polia.

Vlastnosti polí sa kontrolujú podľa vlastností, ktoré schemas/block.json deklaruje pre každý vstavaný typ poľa, a tiež podľa vlastností, ktoré prijíma každé pole. Táto kontrola nezahŕňa vlastnosti špecifické pre obaly v odkazoch custom/* ani typy polí s menným priestorom definované v projekte. Naďalej platí existujúca validácia typov polí a vlastných odkazov. Identifikátory sú blockstudio.blockJson.property a blockstudio.fieldJson.property.

Kontrolujú sa názvy vlastností, nielen ich hodnoty: minimized je platné pre opakovač, ale pri textovom poli sa nahlási. Správanie doplnku za behu sa nemení. Ak projekt zámerne pridáva vlastné metadáta k vstavaným poliam, potlačte iba tieto upozornenia bez vypnutia ostatných kontrol štruktúry:

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

Vstavané polia v opakovane použiteľnom field.json sa kontrolujú aj vtedy, keď má odkaz custom/* vlastné možnosti obalu. Súbory rozšírení nespadajú do rozsahu tejto diagnostiky názvov vlastností; pravidlá set špecifické pre rozšírenia zostávajú platné.

field.json (vlastné opätovne použiteľné polia):

  • Chýba name
  • Chýba alebo je prázdne attributes
  • Neplatné objekty atribútov alebo chýbajúce pole type
  • Chýba id pri poliach hodnôt, ktoré ho vyžadujú
  • Neznáme typy polí
  • Vlastnosti poľa, ktoré daný typ poľa neprijíma
  • Pole tabs v opakovači, priamo alebo v skupine bez id
  • Chýbajúce, nejednoznačné, neplatné alebo cyklické vnorené odkazy custom/*

Rozšírenie JSON (rozšírenia blokov v extensions/):

  • Chýba name (cieľový blok)
  • Chýba kľúč blockstudio
  • Chýba kľúč blockstudio.extend

page.json (stránky založené na súboroch):

  • Chýba title
  • Chýba slug
  • Neplatné hodnoty postStatus

db.php:

  • Chýba pole fields
  • Neplatné typy polí
  • Podporuje staršie polia aj Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Neplatné metódy HTTP
  • Nesprávna hodnota public (musí byť true, false alebo 'open')
  • Podporuje staršie polia aj návratové hodnoty objektov s atribútmi

cron.php:

  • V nakonfigurovaných úlohách chýba schedule
  • V nakonfigurovaných úlohách chýba callback
  • Podporuje staršie polia aj návratové hodnoty objektov s atribútmi

blockstudio.json:

  • Skrátené logické hodnoty, napríklad "tailwind": true (musí sa použiť vnorený formát objektu {"enabled": true, "config": ""})

Konfigurácia

Rozšírenie štandardne vyhľadáva súbory Blockstudio v analyzovanom projekte. Ak projekt používa bloky alebo opakovane použiteľné polia z knižnice mimo koreňového adresára projektu, pridajte cestu ku knižnici do blockstudioScanRoots. Cesta sa preveruje na definície block.json aj field.json, takže externé značky blokov a ich vlastné polia možno overovať spoločne.

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

Ak chcete súbory ignorovať, použite štandardnú konfiguráciu excludePaths pre PHPStan.

Predvoľby analýzy

Automaticky objavené rozšírenie zostáva bezpečným základom z hľadiska kompatibility. Blockstudio 7.6 pridáva voliteľné vrstvy bez zmeny existujúcich projektov:

Predvoľba Správanie
base.neon Analýza existujúcej schémy, šablón, hákov, nastavení a API.
theme.neon Základ plus koreňové adresáre tém WordPress, hlavičky štýlov, zdroje Blockstudio, obmedzenie selektorov, predvolené hodnoty polí a limity opakovačov.
extreme-theme.neon Téma plus PHPStan max, nebezpečné PHP, escapovanie výstupu, Tailwind, JavaScript a kontroly Interactivity API.
wordpress-render.neon Extrémna téma plus živá renderovacia sonda WordPress dodaná volajúcim.

Inštalácia blockstudio/phpstan aktivuje iba základné rozšírenie. Ak chcete použiť voliteľnú vrstvu, zahrňte ju do existujúcej konfigurácie PHPStan:

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

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

blockstudioThemeExcludePaths riadi skener tém. Štandardná konfigurácia excludePaths pre PHPStan nezávisle riadi analýzu PHP.

Nastavenie phpstan.excludePaths kanonického príkazu v blockstudio.json (a jeho voľba --exclude) konfigurujú obe vrstvy. Relatívne vzory sa vyhodnocujú voči každému nakonfigurovanému koreňovému adresáru, takže položky ako vendor/** obmedzujú analýzu PHPStan aj skenovanie projektu v Blockstudio.

Vzor označujúci jeden adresár, napríklad _dist/** alebo node_modules/**, vylúči tento adresár všade, kde sa nachádza, nielen vedľa koreňového adresára témy. Vzor obsahujúci lomku, napríklad assets/*/docs/**, zostáva ukotvený ku koreňovému adresáru. Vygenerované zdroje blokov sa nachádzajú v adresári _dist v každom bloku, preto forma s názvom jedného adresára zabráni zahrnutiu skompilovaného výstupu do analýzy.

Kanonický príkaz

Balík nainštaluje vendor/bin/blockstudio-phpstan ako spustiteľný súbor na analýzu. Ak projekt nevyberie inú predvoľbu, použije predvoľbu base. Samotná inštalácia balíka teda neaktivuje vrstvy témy ani extrémnej témy:

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

Predvoľby už obsahujú samotné rozšírenie. Do projektu, ktorý spúšťa kanonický príkaz, nepridávajte phpstan/extension-installer: ak je prítomný inštalátor, extension.neon sa načíta dvakrát a PHPStan sa zastaví s hlásením „Tento súbor je zahrnutý viackrát“ ešte pred spustením analýzy.

Príkaz predvolene nastavuje pre PHPStan limit pamäte 1G, aby projekty WordPress spravované cez Composer nezdedili bežný limit CLI 128M. Ak ho chcete zmeniť, zadajte po -- explicitnú voľbu PHPStan, napríklad -- --memory-limit=512M --no-progress.

Zavedenie analýzy v existujúcom projekte

Prvé spustenie zvyčajne odhalí problémy v projekte, ktorý ešte nebol analyzovaný. Namiesto zníženia úrovne predvoľby vytvorte základný súbor PHPStan a nasmerujte phpstan.configuration na konfiguráciu projektu, ktorá ho zahŕňa. Na nový kód sa potom vzťahuje plná predvoľba a zaznamenané nálezy neprekážajú:

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

Pre predvoľby base a theme ponechajte riadok level. Kanonický príkaz pre ne nastaví úroveň max iba vtedy, keď nie je zahrnutá konfigurácia projektu. Bez úrovne PHPStan sa zastaví s hlásením „Neboli zistené žiadne pravidlá“. Predvoľba extreme-theme nastavuje úroveň max sama.

Relatívne cesty sa vyhodnocujú od blockstudio.json. Kanonický príkaz aj spravovaný hák pre potvrdenie zmien tento súbor prevezmú, takže hák kontroluje nové nálezy bez toho, aby bolo najprv potrebné vyriešiť nevybavené nálezy.

Predvolené hodnoty príkazov pre celý projekt ponechajte v blockstudio.json:

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

Relatívne koreňové adresáre sa vyhodnocujú od súboru, v ktorom sú deklarované. Explicitné hodnoty CLI nahrádzajú zodpovedajúce hodnoty JSON. Ak chcete použiť iný zdroj konfigurácie, zadajte --blockstudio-json path/to/project.json. Chybný JSON, nepodporované kľúče phpstan, neplatné hodnoty a chýbajúci explicitný zdroj vedú deterministicky k ukončeniu s návratovým kódom 2.

Vyberte inú predvoľbu, zahrňte konfiguráciu projektu, pridajte opakovateľné koreňové adresáre a vylúčenia alebo požiadajte PHPStan o JSON:

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

Obalový skript skladá konfiguráciu v dočasnom systémovom adresári a pri ukončení ju odstráni. Do analyzovaného projektu nikdy nezapisuje vygenerovanú konfiguráciu, základné súbory, háky ani vyrovnávaciu pamäť. Volajúci môžu napriek tomu explicitne nastaviť bežnú vyrovnávaciu pamäť pre PHPStan.

Zmluva o návratových kódoch:

  • 0 pri úspešnej analýze
  • 1, keď PHPStan nahlási diagnostické správy
  • 2 pri nesprávnom použití, chybe konfigurácie alebo vykonávania procesu

Spravovaná kontrola pri commite

Ak chcete z analýzy extrémnej témy urobiť podmienku potvrdenia zmien v repozitári, povoľte hák spravovaný cez Blockstudio v blockstudio.json:

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

Po nainštalovaní závislostí alebo zmene nastavenia ho synchronizujte:

Shell
vendor/bin/blockstudio-githooks sync

Príkaz zapisuje vygenerovaný hák pred potvrdením zmien aj záznam o jeho správe do spoločného adresára Git, nastaví core.hooksPath na adresár spravovaných hákov a bezpečne nadviaže na predtým nakonfigurovaný hák pred potvrdením zmien. Opakovaná synchronizácia aktualizuje iba vygenerovaný súbor, takže aktualizácie balíka sú idempotentné.

Nastavte commit na false, odstráňte ho alebo odstráňte blockstudio.json a potom spustite sync, aby sa obnovila zaznamenaná cesta k háku a odstránili iba súbory spravované cez Blockstudio. Môžete tiež spustiť:

Shell
vendor/bin/blockstudio-githooks remove

Súbory spravované používateľom sa nikdy neprepisujú ani neodstraňujú. Ak niekto po povolení Blockstudio zmení core.hooksPath, pri odstránení sa toto novšie nastavenie zachová. Vygenerovaný hák podporuje prepojené pracovné kópie Git aj cesty obsahujúce medzery, pretože v čase potvrdenia zmien zisťuje aktívny repozitár a koreňový adresár projektu. Kanonický príkaz spúšťa z tohto koreňového adresára, takže ten istý objekt phpstan riadi interaktívne spustenia aj potvrdenia zmien bez duplicitne vygenerovaných argumentov.

Hák spúšťa iba vendor/bin/blockstudio-phpstan. Blockstudio nespúšťa formátovač a hák nikdy neprepisuje súbory projektu. Chýbajúce závislosti a zlyhania analýzy zablokujú potvrdenie zmien a zobrazia pokyny na riešenie problému.

Živé vykresľovanie WordPress

Živá vrstva je zámerne explicitná. Volajúci spravuje prostredie WordPress a poskytuje pole argv:

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

Príkaz sa spúšťa bez shellu a musí vypísať jeden objekt JSON:

JSON
{"ok":true}

Sonda môže nahlásiť konkrétnu chybu:

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

Nenulové návratové kódy, časové limity, chybný JSON a ok: false vedú k blockstudio.wordpress.render.

blockstudio.javascript.domContract nahlasuje selektor atribútu [data-*], ktorý skript odovzdá do querySelector(), querySelectorAll(), closest() alebo matches(), ak žiadna analyzovaná značka tento atribút nemá. Značky zahŕňajú každý súbor PHP, Twig, Blade a HTML, ako aj každý komponent React .tsx a .jsx v analyzovaných koreňových priečinkoch, okrem vylúčených ciest. Komponenty sa parsujú: počítajú sa názvy atribútov JSX aj reťazcové kľúče objektových literálov, takže objekt atribútov rozbalený do prvku vyhovuje selektoru, zatiaľ čo názvy tried a iné hodnoty atribútov nie.

Kontroly API Interactivity čítajú tie isté komponenty React. Menný priestor data-wp-interactive na prvku JSX sa považuje za odkaz na šablónu pre blockstudio.interactivity.orphan a direktívy data-wp-* v ňom sa vyhodnocujú podľa najbližšieho nadradeného menného priestoru alebo podľa predpony namespace:: v hodnote. Direktívy so statickou reťazcovou hodnotou, zapísanou ako atribút JSX alebo ako reťazcový kľúč objektu atribútov, musia odkazovať na existujúce obslužné funkcie a cesty úložiska (blockstudio.interactivity.handler, blockstudio.interactivity.binding) a kód úložiska nesmie meniť atribúty ani triedy, na ktoré sú naviazané (blockstudio.interactivity.derivedState). React escapuje hodnoty atribútov, preto sa data-wp-context v komponente nehlási; dynamické hodnoty sa nekontrolujú. Menné priestory pod bsui/ patria k pribaleným blokom UI, ktorých úložiská sa dodávajú s Blockstudio mimo analyzovaných koreňových priečinkov, takže nikdy nie sú osirelé.

Identifikátory diagnostických správ

Nová diagnostika predvolieb si zachováva stabilné identifikátory blockstudio.*:

  • Štruktúra témy: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Zdroje a polia: 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
  • Interaktivita: 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

Výkon

Skener prijíma bežné zmaterializované adresáre, odstraňuje duplicitné koreňové adresáre, preskakuje adresáre závislostí, zostavení a vyrovnávacej pamäte, ukladá načítané súbory do pamäte a triedi diagnostické správy deterministicky. Udržujte koreňové adresáre úzke, vylúčte testovacie a generované adresáre a pre veľké repozitáre nastavte limit počtu súborov. JavaScript a Tailwind možno vypnúť nezávisle. Živé vykresľovanie sa spustí iba po výbere príslušnej predvoľby.

Diagnostické správy pre témy, JavaScript a Tailwind sa oznamujú cez vyrovnávaciu pamäť výsledkov PHPStan. Ak zmeníte iba block.json alebo skript, teplá vyrovnávacia pamäť môže vrátiť predchádzajúci výsledok. Ak chcete pri overovaní takýchto zmien obísť vyrovnávaciu pamäť, zadajte po -- voľbu --debug.

Zmluva projektu pre kódovacích agentov

Balík nainštaluje tretí spustiteľný súbor vendor/bin/blockstudio-agents. Ten zapíše súbor AGENTS.md s opisom projektu, v ktorom sa spúšťa. Kódovací agent ho potrebuje skôr, než sa čohokoľvek dotkne: čo projekt vytvára, ktoré funkcie Blockstudio sú povolené, ktoré problémy analýza zamietne a ktoré príkazy sa používajú.

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

Žiadny riadok výstupu nie je pevne danou šablónou. Každý vychádza z jedného z troch zdrojov:

  • Vlastné súbory projektu. Téma s hlavičkou style.css, blokmi a stránkami uloženými v súboroch vytvorí iný dokument než doplnok, ktorý registruje bloky a nič iné. Počty, adresáre, menné priestory blokov a jazyky šablón zodpovedajú skutočným zisteniam skenera pri použití rovnakých koreňových adresárov a vylúčení ako pri analýze.
  • blockstudio.json. Opisujú sa iba povolené funkcie vrátane nakonfigurovaných hodnôt: predpony značiek blokov a menné priestory, cez ktoré sa rozpoznávajú, Tailwind, pribalený UI, reset zdrojov editora, cesta k vyrovnávacej pamäti, profil výkonu, statické predvykresľovanie a jeho dynamické cesty, predvolené hodnoty témy, Content Sync a hák pri potvrdení zmien.
  • Vybraná predvoľba phpstan.preset. Sekcia správnosti sa číta priamo zo súborov predvolieb po jednotlivých vrstvách, takže uvádza presne tie pravidlá, ktoré predvoľba registruje. Pri base opisuje pravidlá pre schému, šablóny, háky a nastavenia. Pri extreme-theme opisuje aj pravidlá štruktúry témy, prísne príznaky PHPStan, nebezpečné PHP, escapovanie výstupu, Tailwind a JavaScript. Ak predvoľba získa nové pravidlo, zmení sa aj vygenerovaný dokument.

Sekcia príkazov funguje rovnako. wp bs prerender status sa zobrazí, keď je povolené statické predvykresľovanie, vendor/bin/blockstudio-githooks sync, keď je nastavené githooks.commit, a wp bs db schemas, keď projekt skutočne obsahuje db.php.

Možnosť Správanie
--root <path> Koreňový adresár projektu (predvolené: aktuálny adresár)
--config <path> Cesta k blockstudio.json (predvolené: <root>/blockstudio.json)
--output <path> Cesta k zmluve (predvolené: <root>/AGENTS.md)
--stdout Vypíše zmluvu namiesto jej zápisu
--check Ukončí sa s kódom 1, ak zmluva na disku nie je aktuálna
--force Nahradí súbor, ktorý Blockstudio nespravuje

--check umožňuje použiť zmluvu ako podmienku CI, podobne ako hák pri potvrdení zmien podmieňuje analýzu:

Shell
vendor/bin/blockstudio-agents --check

Správa súborov

Vygenerovaný súbor obsahuje rovnaký typ značky ako spravovaný hák pri potvrdení zmien a platí preň rovnaké pravidlo: Blockstudio nikdy nenahrádza súbor, ktorý nevytvoril. Ak súbor AGENTS.md existoval ešte pred zavedením príkazu alebo ho autor vytvoril ručne, operácia bude odmietnutá s návratovým kódom 2 a súbor zostane nedotknutý, kým sa nezadá --force.

Opätovné generovanie je bezpečné. Súbor sa končí oblasťou poznámok a bajty medzi jej značkami zostávajú zachované pri každom generovaní:

Markdown
## Project notes

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

Návratové kódy: 0 pri zápise, aktuálnosti alebo výpise zmluvy, 1, keď --check zistí zastaranú zmluvu, a 2 pri chybách použitia, konfigurácie alebo súborového systému.

Tvary typov polí

Rozšírenie mapuje každý typ poľa Blockstudio na konkrétny typ PHP:

Typ poľa Typ PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (jedno) string|int
select, checkbox (viacero) 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 (jedno) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (viacero) list<array{id: int, url: string, ...}>
group Pomenované skupiny používajú predpony s podčiarkovníkom; anonymné skupiny sa zlúčia do nadradeného rozsahu
repeater list<array{...child fields...}>
tabs Zlúčené do nadradeného rozsahu

Zástupné definície API

Rozšírenie obsahuje zástupné definície pre celé verejné rozhranie Blockstudio API:

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

Poskytujú automatické dopĺňanie a kontrolu typov bez potreby mať v počítači zdrojový kód doplnku Blockstudio.

Požiadavky

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (odporúčané na automatické vyhľadávanie)

Balík automaticky nainštaluje poskytovateľa kompatibility s BC Math. Natívne ext-bcmath je preto voliteľné, a to aj pri novovygenerovaných témach, ktoré aktivujú kontroly JavaScript cez predvoľbu témy alebo extrémnej témy.