Přejít k obsahu

PHPStan

Rozšíření blockstudio/phpstan přidává statickou analýzu do projektů Blockstudio. Během analýzy ověřuje šablony bloků, soubory schémat, cesty k nastavením a názvy hooků, takže odhalí chyby dřív, než se projeví za běhu.

Instalace

Shell
composer require --dev blockstudio/phpstan

Typování šablon ve verzi 7.7 a rozšířené kontroly značek bloků vyžadují blockstudio/phpstan 0.1.9 nebo novější a PHPStan 2.1.47 nebo novější. Aktualizujte balíček zvlášť od pluginu:

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

Rozšíření se automaticky najde prostřednictvím instalátoru rozšíření PHPStan. Ruční konfigurace není potřeba.

Co kontroluje

Přístup k polím šablony

Pokud se soubor PHP nachází vedle souboru block.json, rozšíření ověří každý přístup $a['key'] podle deklarovaných atributů bloku.

PHP
<?php

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

Rozšíření ví, že Blockstudio definuje $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview a proměnné islandů ještě před vložením šablony. Přímé čtení, například $a['title'], proto nehlásí jako možná nedefinované a typ $a odvodí ze souboru block.json vedle šablony. Tvar se zachová i při zužování typu, takže $a['label'] ?? '', isset( $a['cta']['target'] ) a $a['cta']['title'] !== null si ponechají deklarované typy polí; proměnná $a si zachová typ, který jí šablona přiřadila. Nepřidávejte dokumentační blok /** @var array<string, mixed> $a */: nahradil by tento tvar otevřeným polem.

Klíče polí se řídí pravidly zploštění za běhu v Blockstudio. Kontejnery tabs a anonymní group bez id slouží pouze k prezentaci, takže jejich podřízená pole zůstávají v rozsahu nadřazeného prvku. Skupina s názvem přidá ID skupiny jako prefix klíčů svých podřízených polí:

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

Opakovaně použitelná vlastní pole

Odkazy custom/* na soubory se rozbalí před kontrolou klíčů šablony a tvarů polí. Rozšíření načte odpovídající field.json a uplatní stejná pravidla pro idStructure, overrides, vnořené odkazy, skupiny, karty a opakovače jako 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é klíče šablony jsou title a hero_description. Jsou rozpoznány v PHP, Twig, Blade, značkách bloků i odvozených tvarech atributů.

Pokud definice založená na souboru chybí, je nejednoznačná, neplatná nebo cyklická, zobrazí se konkrétní chyba blockstudio.customField.*. Kontroly závislých klíčů se pro daný blok přeskočí, aby jediná nevyřešená definice nevyvolala další vlnu falešných chyb o neznámých polích.

Definice registrované pouze za běhu prostřednictvím filtru blockstudio/fields PHP nelze při statické analýze odvodit. Pokud má pole přispívat ke staticky kontrolovaným klíčům šablony, použijte definici field.json.

Přístup k šablonám Twig

Šablony Twig se prohledávají automaticky. Anotace není potřeba.

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

Přístup k šablonám Blade

Šablony Blade se prohledávají stejným způsobem.

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

Ověřování značek bloků

Značky bloků se ověřují na místech, kde je Blockstudio načítá: u značek <bs:> a <block>, značek s prefixy nastavenými v blockTags.prefixes (například <acme-card>, které se rozpoznávají v pořadí jmenných prostorů stejně jako za běhu) a aliasů, v šablonách bloků PHP, Twig a Blade i v rozvrženích stránek. Kontrolují se také zdroje stránek pod pages/ (index.php, index.html, index.twig, index.blade.php), včetně elementů HTML, které projekt mapuje na bloky. Dodávané bloky UI jsou rozpoznány, pokud je zapnuto 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) -->

Atribut je přijat, pokud jej blok deklaruje jako pole (včetně vlastních polí a polí, která pole typu blok předává v rámci idStructure) nebo pokud jej do kořenového elementu bloku předává Blockstudio: data-*, aria-*, id, style, role, title, lang, dir, hidden a tabindex. V šablonách se předává každý atribut html-*; ve zdrojích stránek prefix html- označuje pouze jeden z předávaných atributů. Vše ostatní se hlásí, především nede­klarované class, protože Blockstudio tento atribut ukládá, ale nikdy jej nevykreslí.

Za běhu registruje mapování elementů a aliasy značek pomocí filtrů PHP, které statická analýza nedokáže vyhodnotit, a proto je načítá z blockstudio.json. scanPhp kontroluje také značky v dalších souborech projektu PHP, například značky komponent v modulech, aniž by tam hlásilo neznámé 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
    }
  }
}

Element se mapuje na název bloku nebo na pravidla zkoušená v daném pořadí: použije se první pravidlo, jehož atribut element obsahuje; prostý název bloku odpovídá vždy. Elementy, které projekt nemapuje, si ponechají svůj základní blok a nekontrolují se. Diagnostika používá blockstudio.blockTag.unknown, blockstudio.blockTag.attribute a blockstudio.blockTag.class.

Typování záznamů databáze

Db::get() vrací typovanou instanci podle schématu db.php. Tvary záznamů se odvozují 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á pole nemohou mít hodnotu null. Volitelná pole jsou type|null. Pole typu id (int) je vždy přítomné. Stejné typování funguje i se syntaxí nástroje PHP Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Ověřování cest k nastavením

Cesty Settings::get() se ověřují podle známého schématu nastavení.

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

Ověřování názvů hooků

Názvy hooků filtrů a akcí Blockstudio se ověřují.

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

Dynamické hooky nastavení, jako je blockstudio/settings/tailwind/enabled, jsou vždy povolené. Hooky nesouvisející s blockstudio se ignorují.

Ověřování schémat

Rozšíření ověřuje všechny soubory schémat Blockstudio v projektu.

block.json:

  • Chybí pole name
  • Chybí pole type
  • U hodnotových polí chybí id, které je pro ně povinné
  • Neznámé typy polí
  • Vlastnosti polí, které daný typ nepřijímá, například "translat" místo "translate", s návrhem nejbližší známé vlastnosti
  • select/radio/checkbox bez options nebo populate
  • Duplicitní ID polí
  • Pole tabs uvnitř opakovače, přímo nebo ve skupině bez id
  • Neplatné deklarace pluginDependencies

Kontejnerová pole, jako jsou group a tabs, i odkazy na pole custom/* mohou vynechat id, pokud pouze rozbalují nebo obalují jiná pole.

Vlastnosti polí se kontrolují podle vlastností schemas/block.json, které deklaruje pro každý vestavěný typ pole, a také podle vlastností přijímaných všemi poli. Vlastnosti specifické pro obal u odkazů custom/* a typy polí s názvy v prostoru jmen definované projektem tato kontrola nezahrnuje. Stávající ověřování typů polí a vlastních odkazů zůstává v platnosti. Identifikátory jsou blockstudio.blockJson.property a blockstudio.fieldJson.property.

Kontrolují se názvy vlastností, nejen jejich hodnoty: minimized je platné u opakovače, ale u textového pole se nahlásí. Chování pluginu za běhu se nemění. Pokud projekt záměrně připojuje k vestavěným polím vlastní metadata, potlačte pouze tato upozornění, aniž byste vypnuli ostatní kontroly struktury:

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

Vestavěná pole uvnitř opakovaně použitelného field.json se stále kontrolují, i když má odkaz custom/* vlastní možnosti obalu. Soubory rozšíření jsou mimo rozsah této diagnostiky názvů vlastností; pravidla set specifická pro rozšíření zůstávají platná.

field.json (opakovaně použitelná vlastní pole):

  • Chybí name
  • Chybí nebo je prázdné attributes
  • Neplatné objekty atributů nebo chybějící type pole
  • Chybí id u hodnotových polí, která jej vyžadují
  • Neznámé typy polí
  • Vlastnosti polí, které daný typ pole nepřijímá
  • Pole tabs uvnitř opakovače, přímo nebo ve skupině bez id
  • Chybějící, nejednoznačné, neplatné nebo cyklické vnořené odkazy custom/*

Rozšíření JSON (rozšíření bloků v extensions/):

  • Chybějící name (cílový blok)
  • Chybějící klíč blockstudio
  • Chybějící klíč blockstudio.extend

page.json (stránky založené na souborech):

  • Chybí title
  • Chybí slug
  • Neplatné hodnoty postStatus

db.php:

  • Chybí pole fields
  • Neplatné typy polí
  • Podporuje starší pole i Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Neplatné metody HTTP
  • Nesprávná hodnota public (musí být true, false nebo 'open')
  • Podporuje starší pole i vrácené objekty s atributy

cron.php:

  • U nakonfigurovaných úloh chybí schedule
  • U nakonfigurovaných úloh chybí callback
  • Podporuje starší pole i vrácené objekty s atributy

blockstudio.json:

  • Zkrácené booleovské zápisy jako "tailwind": true (je nutné použít vnořený formát objektu {"enabled": true, "config": ""})

Konfigurace

Rozšíření ve výchozím nastavení vyhledává soubory Blockstudio v analyzovaném projektu. Pokud projekt používá bloky nebo opakovaně použitelné položky z knihovny mimo kořenový adresář projektu, přidejte cestu ke knihovně do blockstudioScanRoots. Cesta se prohledává kvůli definicím block.json i field.json, takže lze společně ověřovat externí značky bloků i jejich vlastní pole.

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

Chcete-li některé soubory ignorovat, použijte standardní konfiguraci excludePaths nástroje PHPStan.

Předvolby analýzy

Automaticky nalezené rozšíření zůstává základem zajišťujícím kompatibilitu. Blockstudio Verze 7.6 přidává volitelné vrstvy, aniž by měnila stávající projekty:

Předvolba Chování
base.neon Stávající analýza schémat, šablon, hooků, nastavení a API.
theme.neon Základní předvolba doplněná o kořenové adresáře WordPress šablony, hlavičky stylů, prostředky Blockstudio, omezení rozsahu selektorů, výchozí hodnoty polí a limity opakovačů.
extreme-theme.neon Předvolba Theme doplněná o PHPStan max, nebezpečné PHP, escapování výstupu, Tailwind, JavaScript a kontroly API Interactivity.
wordpress-render.neon Extrémní předvolba Theme doplněná o živou testovací sondu WordPress zadanou volajícím.

Instalací blockstudio/phpstan se aktivuje pouze základní rozšíření. Chcete-li přidat volitelnou vrstvu, zahrňte ji do stávající konfigurace PHPStan:

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

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

blockstudioThemeExcludePaths ovládá skener šablon. Standardní excludePaths nástroje PHPStan samostatně ovládá analýzu PHP.

Nastavení phpstan.excludePaths kanonického příkazu v blockstudio.json (a jeho volba --exclude) konfiguruje obě vrstvy. Relativní vzory se vyhodnocují vůči každému nakonfigurovanému kořeni, takže položky jako vendor/** omezují analýzu PHPStan i skenování projektu nástrojem Blockstudio.

Vzorek označující jeden adresář, například _dist/** nebo node_modules/**, vyloučí tento adresář bez ohledu na jeho umístění, nejen vedle kořenového adresáře šablony. Vzorek obsahující lomítko, například assets/*/docs/**, zůstává navázaný na kořen. Vygenerované prostředky bloku jsou uložené v adresáři _dist uvnitř každého bloku, takže forma s názvem jednoho adresáře zabrání zahrnutí zkompilovaného výstupu do analýzy.

Kanonický příkaz

Balíček instaluje vendor/bin/blockstudio-phpstan jako spustitelný soubor pro analýzu. Pokud projekt nezvolí jinou, použije se předvolba base. Samotná instalace balíčku tedy neaktivuje vrstvy Theme ani Extreme Theme:

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

Předvolby obsahují samotné rozšíření. Do projektu, který spouští kanonický příkaz, nepřidávejte phpstan/extension-installer: pokud je nainstalováno, načte se extension.neon dvakrát a PHPStan se zastaví s hlášením „Tento soubor je zahrnut vícekrát“ ještě před zahájením analýzy.

Příkaz ve výchozím nastavení nastaví PHPStan na limit paměti 1G, aby projekty WordPress spravované pomocí Composer nepodléhaly obvyklému limitu CLI 128M. Chcete-li toto nastavení přepsat, zadejte za -- explicitní volbu PHPStan, například -- --memory-limit=512M --no-progress.

Zavedení analýzy do stávajícího projektu

Projekt, který dosud nebyl analyzován, při prvním spuštění obvykle nahlásí problémy. Místo snížení úrovně předvolby vygenerujte základní soubor PHPStan a nasměrujte phpstan.configuration na konfiguraci projektu, která jej zahrnuje. Nový kód pak musí splňovat požadavky celé předvolby, zatímco zaznamenané problémy nebudou překážet:

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

Pro předvolby base a theme ponechte řádek level. Kanonický příkaz nastaví pro ně úroveň max pouze tehdy, když není zahrnuta žádná konfigurace projektu; bez úrovně PHPStan se zastaví s hlášením „Nebyla nalezena žádná pravidla“. Předvolba extreme-theme nastavuje úroveň max sama.

Relativní cesty se vyhodnocují od blockstudio.json. Kanonický příkaz i spravovaný hook pro potvrzování změn soubor najdou, takže hook kontroluje nové nálezy, aniž by bylo nutné nejprve vyřešit všechny dosavadní problémy.

Výchozí hodnoty příkazů pro celý projekt ponechte v blockstudio.json:

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

Relativní kořenové cesty se vyhodnocují od souboru, který je deklaruje. Explicitní hodnoty CLI nahrazují odpovídající hodnoty JSON. Alternativní zdroj konfigurace zadáte pomocí --blockstudio-json path/to/project.json. Chybně formátované JSON, nepodporované klíče phpstan, neplatné hodnoty a chybějící explicitní zdroj způsobí předvídatelné ukončení s návratovým kódem 2.

Vyberte jinou předvolbu, zahrňte konfiguraci projektu, přidejte opakovatelně zadávané kořenové adresáře a výjimky nebo požádejte 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 skládá konfiguraci v dočasném systémovém adresáři a při ukončení ji smaže. Do analyzovaného projektu nikdy nezapisuje vygenerovanou konfiguraci, základní soubory, hooky ani mezipaměti. Volající přesto mohou výslovně nakonfigurovat obvyklou mezipaměť nástroje PHPStan.

Návratové hodnoty jsou následující:

  • 0 při úspěšné analýze
  • 1 pokud PHPStan nahlásí diagnostická hlášení
  • 2 při nesprávném použití, chybě konfigurace nebo spuštění procesu

Spravovaný commit hook

Chcete-li z analýzy Extreme Theme udělat kontrolní bránu při potvrzování změn do repozitáře, aktivujte hook spravovaný nástrojem Blockstudio v blockstudio.json:

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

Po instalaci závislostí nebo změně nastavení jej synchronizujte:

Shell
vendor/bin/blockstudio-githooks sync

Příkaz zapíše vygenerovaný hook pro potvrzování změn a záznam o jeho vlastnictví do společného adresáře nástroje Git, nastaví core.hooksPath na adresář spravovaného hooku a bezpečně naváže na dříve nakonfigurovaný hook pro potvrzování změn. Opakovaná synchronizace obnovuje pouze vygenerovaný soubor, takže aktualizace balíčku lze provádět opakovaně bez vedlejších účinků.

Nastavte commit na false, odeberte jej nebo odeberte blockstudio.json a potom spusťte sync, aby se obnovila zaznamenaná cesta k hooku a odstranily pouze soubory vlastněné Blockstudio. Můžete také spustit:

Shell
vendor/bin/blockstudio-githooks remove

Soubory vlastněné uživatelem se nikdy nepřepisují ani nemažou. Pokud někdo změní core.hooksPath po aktivaci Blockstudio, při odebrání zůstane toto novější nastavení zachováno. Vygenerovaný hook podporuje propojené pracovní kopie Git i cesty obsahující mezery, protože při potvrzování změn zjišťuje aktivní repozitář a kořen projektu. Kanonický příkaz spouští z tohoto kořene, takže stejný objekt phpstan řídí interaktivní spuštění i potvrzování změn bez duplicitních vygenerovaných argumentů.

Hook spouští pouze vendor/bin/blockstudio-phpstan. Blockstudio nespouští formátovač a hook nikdy nepřepisuje soubory projektu. Chybějící závislosti a chyby analýzy zablokují potvrzení změn a zobrazí konkrétní pokyny k nápravě.

Živé vykreslování WordPress

Živá vrstva je záměrně explicitní. Volající odpovídá za prostředí WordPress a předává 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 .

Příkaz se spouští bez shellu a musí vypsat jeden objekt JSON:

JSON
{"ok":true}

Testovací sonda může nahlásit konkrétní chybu:

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

Návratové kódy jiné než nula, překročení časového limitu, chybně formátované JSON a ok: false vedou k výsledku blockstudio.wordpress.render.

blockstudio.javascript.domContract hlásí selektor atributu [data-*], který skript předává do querySelector(), querySelectorAll(), closest() nebo matches(), pokud tento atribut neobsahuje žádné analyzované značení. Značení zahrnuje všechny soubory PHP, Twig, Blade a HTML a také všechny komponenty React .tsx a .jsx v analyzovaných kořenech po odečtení vyloučených cest. Komponenty se parsují: počítají se názvy atributů JSX i řetězcové klíče objektových literálů, takže objekt atributů rozprostřený na element splňuje selektor, zatímco názvy tříd a jiné hodnoty atributů nikoli.

Kontroly Interactivity API čtou stejné komponenty React. Pro blockstudio.interactivity.orphan se jmenný prostor data-wp-interactive na elementu JSX počítá jako odkaz na šablonu a direktivy data-wp-* uvnitř něj se vyhodnocují podle nejbližšího nadřazeného jmenného prostoru nebo podle předpony namespace:: v hodnotě. Direktivy se statickou řetězcovou hodnotou, zapsané jako atribut JSX nebo jako řetězcový klíč objektu atributů, musí odkazovat na existující obslužné funkce a cesty úložiště (blockstudio.interactivity.handler, blockstudio.interactivity.binding) a kód úložiště nesmí měnit atributy a třídy, na které jsou navázané (blockstudio.interactivity.derivedState). React escapuje hodnoty atributů, takže data-wp-context v komponentě se nehlásí; dynamické hodnoty se nekontrolují. Jmenné prostory pod bsui/ patří k přibaleným blokům UI, jejichž úložiště jsou dodávána s Blockstudio mimo analyzované kořeny, takže nikdy nejsou osiřelá.

Identifikátory diagnostických hlášení

Nová diagnostická hlášení předvoleb zachovávají stabilní ID blockstudio.*:

  • Struktura šablony: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Prostředky a pole: 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

Výkon

Skener přijímá běžné materializované adresáře, odstraňuje duplicitní kořenové cesty, přeskakuje adresáře závislostí, sestavení a mezipamětí, ukládá obsah souborů do mezipaměti v paměti a diagnostická hlášení řadí předvídatelně. Zvolte úzké kořenové cesty, vynechte adresáře s testovacími a generovanými soubory a u velkých repozitářů nastavte limit počtu souborů. JavaScript a Tailwind lze vypnout nezávisle. Živé vykreslování se spustí pouze při výběru příslušné předvolby.

Diagnostická hlášení pro Theme, JavaScript a Tailwind se poskytují prostřednictvím mezipaměti výsledků nástroje PHPStan. Pokud změníte pouze block.json nebo skript, může zahřátá mezipaměť vrátit předchozí výsledek. Chcete-li tyto změny ověřit bez použití mezipaměti, zadejte za -- volbu --debug.

Smlouva o projektu pro programovací agenty

Balíček instaluje třetí spustitelný soubor, vendor/bin/blockstudio-agents. Ten zapíše AGENTS.md s popisem projektu, ve kterém je spuštěn. Právě to programovací agent potřebuje, než začne cokoli měnit: co projekt vytváří, které funkce Blockstudio jsou zapnuté, co analýza odmítne a které příkazy se na projekt vztahují.

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

Žádná část výstupu není pevnou šablonou. Každý řádek vychází z jednoho ze tří zdrojů:

  • Vlastní soubory projektu. Šablona s hlavičkou style.css, bloky a stránkami uloženými v souborech vytvoří jiný dokument než plugin, který registruje pouze bloky. Počty, adresáře, jmenné prostory bloků a jazyky šablon odpovídají skutečným výsledkům skenování, které používá stejné kořenové cesty a výjimky jako analýza.
  • blockstudio.json. Popisují se pouze zapnuté funkce a jejich nakonfigurované hodnoty: předpony značek bloků a jmenné prostory, přes které se vyhodnocují, Tailwind, přibalené UI, reset prostředků editoru, cesta k mezipaměti, profil výkonu, statické předběžné vykreslování a jeho dynamické cesty, výchozí hodnoty šablony, synchronizace obsahu a hook pro potvrzování změn.
  • Vybraná phpstan.preset. Část o správnosti se čte přímo ze souborů předvoleb, vrstvu po vrstvě, a uvádí přesně ta pravidla, která předvolba registruje. Předvolba base popisuje pravidla pro schémata, šablony, hooky a nastavení. Předvolba extreme-theme navíc popisuje pravidla struktury šablony, striktní příznaky PHPStan, nebezpečné PHP, escapování výstupu, Tailwind a JavaScript. Pokud předvolba získá nové pravidlo, změní se podle toho i generovaný dokument.

Sekce s příkazy se řídí stejným principem. wp bs prerender status se zobrazí, je-li zapnuté statické předběžné vykreslování, vendor/bin/blockstudio-githooks sync, pokud je nastaveno githooks.commit, a wp bs db schemas, pokud projekt skutečně obsahuje db.php.

Volba Chování
--root <path> Kořen projektu (výchozí: aktuální adresář)
--config <path> Cesta blockstudio.json (výchozí: <root>/blockstudio.json)
--output <path> Cesta ke smlouvě (výchozí: <root>/AGENTS.md)
--stdout Vypíše smlouvu místo jejího zápisu
--check Ukončí se s kódem 1, pokud smlouva na disku není aktuální
--force Nahradí soubor, který nástroj Blockstudio nevlastní

--check umožňuje použít smlouvu jako kontrolní bránu v CI, stejně jako hook pro potvrzování změn slouží ke kontrole analýzy:

Shell
vendor/bin/blockstudio-agents --check

Vlastnictví

Vygenerovaný soubor obsahuje stejný typ značky jako spravovaný hook pro potvrzování změn a platí stejné pravidlo: Blockstudio nikdy nenahrazuje soubor, který samo nezapsalo. Pokud soubor AGENTS.md existoval již před příkazem nebo jej autor vytvořil ručně, příkaz jeho přepsání odmítne s návratovým kódem 2 a ponechá jej beze změny, dokud nebude zadáno --force.

Bezpečně jej lze generovat opakovaně. Soubor končí oblastí pro poznámky a bajty mezi jejími značkami zůstanou zachovány při každém opětovném generování:

Markdown
## Project notes

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

Návratové kódy jsou 0 při zápisu, aktuálnosti nebo výpisu smlouvy, 1, pokud --check zjistí zastaralou smlouvu, a 2 při chybách použití, konfigurace nebo souborového systému.

Tvary typů polí

Rozšíření mapuje každý typ pole Blockstudio na konkrétní typ PHP:

Typ pole 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 (více) 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 (více) list<array{id: int, url: string, ...}>
group Pojmenované skupiny používají předpony podtržítka; anonymní skupiny se sloučí do nadřazeného rozsahu
repeater list<array{...child fields...}>
tabs Sloučeno do nadřazeného rozsahu

Deklarace typů API

Rozšíření obsahuje deklarace typů pro celé veřejné 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í našeptávání a kontrolu typů bez nutnosti mít ve svém počítači zdrojový kód pluginu Blockstudio.

Požadavky

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (doporučeno pro automatické vyhledávání)

Balíček automaticky instaluje poskytovatele kompatibility BC Math. Nativní ext-bcmath je proto volitelné, a to i u nově generovaných šablon, které aktivují kontroly JavaScript prostřednictvím předvolby Theme nebo Extreme.