Hoppa till innehåll

PHPStan

Tillägget blockstudio/phpstan ger statisk analys till Blockstudio-projekt. Det validerar blockmallar, schemafiler, inställningssökvägar och hooknamn vid analystillfället, så att buggar upptäcks innan de når runtime.

Installation

Shell
composer require --dev blockstudio/phpstan

Malltypningen i 7.7 och de utökade kontrollerna av blocktaggar kräver blockstudio/phpstan 0.1.9 eller senare och PHPStan 2.1.47 eller senare. Uppdatera paketet separat från tillägget:

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

Tillägget upptäcks automatiskt via tilläggsinstalleraren i PHPStan. Ingen manuell konfiguration behövs.

Vad den kontrollerar

Åtkomst till mallfält

När en PHP-fil ligger bredvid en block.json validerar tillägget varje åtkomst till $a['key'] mot blockets deklarerade attribut.

PHP
<?php

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

Tillägget vet att Blockstudio definierar $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview och ö-variablerna innan det inkluderar en mall. Därför rapporteras inte direkta läsningar som $a['title'] som möjligen odefinierade, och typen för $a hämtas från block.json bredvid mallen. Strukturen bevaras vid typförfining, så $a['label'] ?? '', isset( $a['cta']['target'] ) och $a['cta']['title'] !== null behåller de deklarerade fälttyperna; en mall som tilldelar $a självt behåller den typ som tilldelades. Lägg inte till ett docblock av typen /** @var array<string, mixed> $a */: det ersätter strukturen med en öppen array.

Fältnycklar följer Blockstudios regler för utplattning vid körning. tabs och anonyma group-behållare utan id används bara för presentation, så deras underordnade fält ligger kvar i det överordnade omfånget. En namngiven grupp lägger till sitt ID som prefix till underordnade nycklar:

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

Återanvändbara anpassade fält

Filbaserade referenser till custom/* expanderas innan mallnycklar och arraystrukturer kontrolleras. Tillägget läser matchande field.json och tillämpar samma regler för idStructure, overrides, nästlade referenser, grupper, flikar och upprepningsfält som 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" }
        }
      }
    ]
  }
}

De resulterande mallnycklarna är title och hero_description. De känns igen i PHP, Twig, Blade, blocktaggar och härledda attributstrukturer.

Saknade, tvetydiga, ogiltiga eller cykliska filbaserade definitioner ger ett specifikt blockstudio.customField.*-fel. Kontroller av beroende nycklar hoppas över för det blocket så att en olöst definition inte orsakar ytterligare en våg av falska fel om okända fält.

Definitioner som bara registreras vid körning via filtret blockstudio/fields PHP kan inte härledas med statisk analys. Använd en definition av typen field.json när fältet måste bidra med mallnycklar som kontrolleras statiskt.

Mallåtkomst för Twig

Mallar för Twig genomsöks automatiskt. Ingen annotering behövs.

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

Mallåtkomst för Blade

Mallar för Blade genomsöks på samma sätt.

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

Validering av blocktaggar

Blocktaggar valideras där Blockstudio läser dem: taggarna <bs:> och <block>, prefix-taggarna som konfigurerats i blockTags.prefixes (till exempel <acme-card>, som löses i namnrymdsordning liksom vid körning) och aliastaggar i blockmallarna PHP, Twig och Blade samt i sidlayouter. Sidkällor under pages/ (index.php, index.html, index.twig, index.blade.php) kontrolleras också, inklusive elementen HTML som projektet mappar till block. Medföljande UI-block känns igen när ui.enabled är aktiverat.

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

Ett attribut godkänns när blocket deklarerar det som ett fält (inklusive anpassade fält och fält som ett blocktypat fält vidarebefordrar under sitt idStructure), eller när Blockstudio vidarebefordrar det till blockets rotelement: data-*, aria-*, id, style, role, title, lang, dir, hidden och tabindex. I mallar släpps varje attribut i html-* igenom; i sidkällor anger ett html--prefix bara ett av de vidarebefordrade attributen. Allt annat rapporteras, framför allt ett odeklarerat class, eftersom Blockstudio lagrar det utan att någonsin rendera det.

Körningen registrerar elementmappningar och taggalias i PHP-filter, som statisk analys inte kan utvärdera, så analysen läser dem från blockstudio.json. scanPhp kontrollerar också taggar i andra PHP i projektet, till exempel komponentmarkering i moduler, utan att rapportera okända block där:

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

Ett element mappas till ett blocknamn eller till regler som prövas i ordning: den första regeln vars attribut elementet har vinner, och ett vanligt blocknamn matchar alltid. Element som projektet inte mappar behåller sitt kärnblock och kontrolleras inte. Diagnostik använder blockstudio.blockTag.unknown, blockstudio.blockTag.attribute och blockstudio.blockTag.class.

Typning av databasposter

Db::get() returnerar en typad instans baserad på schemat db.php. Poststrukturer härleds automatiskt.

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

Obligatoriska fält kan inte vara null. Valfria fält är type|null. Ett id-fält (int) finns alltid. Samma typning fungerar med den PHP-inbyggda byggarsyntaxen Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Validering av inställningssökvägar

Sökvägar till Settings::get() kontrolleras mot det kända inställningsschemat.

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

Validering av hooknamn

Hooknamn för filter och åtgärder i Blockstudio valideras.

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

Dynamiska inställningshooks som blockstudio/settings/tailwind/enabled tillåts alltid. Hooks som inte hör till blockstudio ignoreras.

Schemavalidering

Tillägget validerar varje sche­mafil av typen Blockstudio i projektet.

block.json:

  • Fältet name saknas
  • Fältet type saknas
  • id saknas för värdefält som kräver ett
  • Okända fälttyper
  • Fältegenskaper som fälttypen inte stöder, till exempel "translat" i stället för "translate", med närmast matchande kända egenskap som förslag
  • select/radio/checkbox utan options eller populate
  • Dubblerade fält-ID:n
  • Ett tabs-fält i en upprepningsgrupp, direkt eller i en grupp utan id
  • Ogiltiga pluginDependencies-deklarationer

Behållarfält som group och tabs samt fältreferenser av typen custom/* kan utelämna id när de bara expanderar eller omsluter andra fält.

Fältegenskaper kontrolleras mot egenskaperna schemas/block.json deklarerar för varje inbyggd fälttyp, samt de egenskaper som alla fält godtar. Wrapper-specifika egenskaper på custom/*-referenser och projektspecifika namnrymda fälttyper omfattas inte av den här kontrollen. Validering av befintliga fälttyper och anpassade referenser gäller fortfarande. Identifierarna är blockstudio.blockJson.property och blockstudio.fieldJson.property.

Det här kontrollerar egenskapsnamn, inte bara deras värden: minimized är giltigt för ett repeaterfält men rapporteras för ett textfält. Pluginets körningsbeteende är oförändrat. Om ett projekt avsiktligt kopplar egna metadata till inbyggda fält kan du undertrycka endast dessa resultat utan att inaktivera andra formkontroller:

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

Inbyggda fält i en återanvändbar field.json kontrolleras fortfarande, även när en custom/*-referens har egna wrapper-alternativ. Tilläggsfiler omfattas inte av dessa diagnostikkontroller av egenskapsnamn; tilläggsspecifika regler för set gäller fortfarande.

field.json (återanvändbara anpassade fält):

  • Saknar name
  • Saknar eller har tomt attributes
  • Ogiltiga attributobjekt eller saknar fältet type
  • Saknar id för värdefält som kräver ett sådant
  • Okända fälttyper
  • Fältegenskaper som fälttypen inte godtar
  • Ett fält av typen tabs i ett repeaterfält, direkt eller i en grupp utan id
  • Saknade, tvetydiga, ogiltiga eller cykliska nästlade custom/*-referenser

Tillägg JSON (blocktillägg i extensions/):

  • Saknat name (målblock)
  • Saknad nyckel blockstudio
  • Saknad nyckel blockstudio.extend

page.json (filbaserade sidor):

  • Saknat title
  • Saknat slug
  • Ogiltiga värden för postStatus

db.php:

  • Saknad array för fields
  • Ogiltiga fälttyper
  • Stöder både äldre arrayer och Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Ogiltiga metoder för HTTP
  • Felaktigt värde för public (måste vara true, false eller 'open')
  • Stöder både äldre arrayer och attributerade objektreturer

cron.php:

  • Saknar schedule för konfigurerade uppgifter
  • Saknar callback för konfigurerade uppgifter
  • Stöder både äldre arrayer och attributförsedda objektreturer

blockstudio.json:

  • Förkortade booleska värden som "tailwind": true (måste använda det nästlade objektformatet {"enabled": true, "config": ""})

Konfiguration

Tillägget hittar som standard Blockstudio-filer i det analyserade projektet. När ett projekt använder block eller återanvändbara fält från ett bibliotek utanför projektroten lägger du till bibliotekssökvägen i blockstudioScanRoots. Sökvägen skannas efter både block.json– och field.json-definitioner, så externa blocktaggar och deras anpassade fält kan valideras tillsammans.

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

Om du vill ignorera filer använder du standardkonfigurationen excludePaths för PHPStan.

Analysförinställningar

Det automatiskt upptäckta tillägget förblir den kompatibilitetssäkra basen. Blockstudio 7.6 lägger till valfria lager utan att ändra befintliga projekt:

Förinställning Beteende
base.neon Analys av befintligt schema, mallar, hookar, inställningar och API.
theme.neon Basen plus temarötter för WordPress, stilmallar, Blockstudio-resurser, selektorskopning, fältstandardvärden och gränser för upprepade fält.
extreme-theme.neon Tema plus PHPStan max, osäkra PHP, utdataescaping, Tailwind, JavaScript och kontroller av Interactivity API.
wordpress-render.neon Extremt tema plus en anroparstyrd aktiv renderingskontroll med WordPress.

Installation av blockstudio/phpstan aktiverar bara bastillägget. Lägg till ett valfritt lager i en befintlig PHPStan-konfiguration:

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

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

blockstudioThemeExcludePaths styr temasökaren. Standardkonfigurationen excludePaths för PHPStan styr analysen av PHP separat.

Inställningen phpstan.excludePaths för det kanoniska kommandot i blockstudio.json (och dess alternativ --exclude) konfigurerar båda lagren. Relativa mönster löses mot varje konfigurerad rot, så poster som vendor/** begränsar analysen av PHPStan såväl som projektgenomsökningen för Blockstudio.

Ett mönster som anger en enskild katalog, till exempel _dist/** eller node_modules/**, utesluter katalogen var den än förekommer, inte bara intill temaroten. Ett mönster med snedstreck, till exempel assets/*/docs/**, förblir förankrat i roten. Genererade blockresurser finns i en katalog _dist i varje block, så formen med en enskild katalog är den som håller kompilerad utdata utanför analysen.

Kanoniskt kommando

Paketet installerar vendor/bin/blockstudio-phpstan som körbart analysprogram. Det kör förinställningen base om inte projektet väljer en annan, så paketinstallationen aktiverar aldrig temalagret eller lagret för extrema teman på egen hand:

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

Förinställningarna inkluderar själva tillägget. Lägg inte till phpstan/extension-installer i ett projekt som kör det kanoniska kommandot: med installationsprogrammet närvarande läses extension.neon in två gånger och PHPStan avbryts med ”This file is included multiple times” innan någon analys görs.

Kommandot ställer som standard in PHPStan på en minnesgräns på 1G, så Composer-hanterade WordPress-projekt inte ärver en typisk gräns på 128M CLI. Skicka ett uttryckligt alternativ PHPStan efter -- för att åsidosätta den, till exempel -- --memory-limit=512M --no-progress.

Införa analys i ett befintligt projekt

Ett projekt som aldrig har analyserats rapporterar vanligtvis resultat vid den första körningen. Sänk förinställningen inte; generera i stället en baslinje PHPStan och ange phpstan.configuration till en projektkonfiguration som inkluderar den. Ny kod kontrolleras då mot hela förinställningen, medan registrerade resultat inte är i vägen:

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

Behåll raden level för förinställningarna base och theme. Det kanoniska kommandot ställer bara in nivån max för dem när ingen projektkonfiguration inkluderas, och utan en nivå PHPStan avbryts körningen med ”No rules detected”. Förinställningen extreme-theme ställer själv in nivån max.

Relativa sökvägar löses från blockstudio.json. Det kanoniska kommandot och den hanterade commit-hooken läser båda in filen, så hooken stoppar nya resultat utan att först kräva att eftersläpningen rensas.

Behåll projektomfattande standardvärden för kommandon i blockstudio.json:

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

Relativa rötter löses från filen som anger dem. Uttryckliga värden för CLI ersätter motsvarande värden för JSON. Skicka --blockstudio-json path/to/project.json för en alternativ konfigurationskälla. Felaktigt formaterad JSON, nycklar i phpstan som inte stöds, ogiltiga värden och en explicit källa som saknas ger ett deterministiskt fel med avslutningskod 2.

Välj en annan förinställning, inkludera en projektkonfiguration, lägg till återkommande rötter och undantag, eller be PHPStan om JSON:

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

Omslaget sammanställer konfigurationen i systemets temporärkatalog och tar bort den vid avslut. Det skriver aldrig genererad konfiguration, baslinjer, hookar eller cachefiler i det analyserade projektet. Anropare kan fortfarande konfigurera PHPStan:s vanliga cache uttryckligen.

Avslutningskoderna är:

  • 0 när analysen godkänns
  • 1 när PHPStan rapporterar diagnostik
  • 2 vid felaktig användning, konfiguration eller processkörning

Hanterad commit-hook

Om du vill göra analysen av extrema teman till en spärr för repository-commits aktiverar du den hook som ägs av Blockstudio i blockstudio.json:

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

Synkronisera den efter att du har installerat beroenden eller ändrat inställningen:

Shell
vendor/bin/blockstudio-githooks sync

Kommandot skriver sin genererade pre-commit-hook och ägarpost i Gits gemensamma katalog, ställer in core.hooksPath på den hanterade hookkatalogen och kedjar säkert ihop den tidigare konfigurerade pre-commit-hooken. Upprepade synkroniseringar uppdaterar bara den genererade filen, så paketuppgraderingar är idempotenta.

Ställ in commit på false, ta bort den eller ta bort blockstudio.json och kör sync för att återställa den registrerade hook-sökvägen och bara ta bort filer som ägs av Blockstudio. Du kan också köra:

Shell
vendor/bin/blockstudio-githooks remove

Filer som ägs av användaren skrivs aldrig över eller tas bort. Om någon ändrar core.hooksPath efter att Blockstudio har aktiverats bevaras den nyare inställningen vid borttagning. Den genererade hooken stöder länkade Git-utcheckningar och sökvägar som innehåller blanksteg genom att identifiera det aktiva repot och projektroten vid commit. Den kör det kanoniska kommandot från den roten, så samma phpstan-objekt styr interaktiva körningar och commits utan duplicerade genererade argument.

Hooken kör endast vendor/bin/blockstudio-phpstan. Blockstudio kör ingen formaterare, och hooken skriver aldrig om projektfiler. Beroenden som saknas och analysfel stoppar commiten med ett felmeddelande som går att åtgärda.

Aktiv rendering med WordPress

Det aktiva lagret är avsiktligt explicit. Anroparen äger miljön WordPress och tillhandahåller en argv-array:

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

Kommandot körs utan ett skal och måste skriva ut ett JSON-objekt:

JSON
{"ok":true}

En kontroll kan rapportera ett avgränsat fel:

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

Avslut med status som inte är noll, tidsgränsöverskridanden, felaktig JSON och ok: false ger blockstudio.wordpress.render.

blockstudio.javascript.domContract rapporterar en attributväljare för [data-*] som ett skript skickar till querySelector(), querySelectorAll(), closest() eller matches() när inget analyserat märkspråk innehåller det attributet. Märkspråk omfattar alla filer av typen PHP, Twig, Blade och HTML samt alla React-komponenter av typen .tsx och .jsx under de analyserade rötterna, minus de undantagna sökvägarna. Komponenter parsas: JSX-attributnamn räknas, liksom strängnycklar i objektliteraler. Därför uppfyller ett attributobjekt som sprids ut på ett element väljaren, medan klassnamn och andra attributvärden inte gör det.

Interactivity API-kontrollerna läser samma React-komponenter. Ett data-wp-interactive-namnrymdsattribut på ett JSX-element räknas som en mallreferens för blockstudio.interactivity.orphan, och direktiven data-wp-* inuti det löses mot den närmast omslutande namnrymden eller ett namespace::-prefix i värdet. Direktiven med ett statiskt strängvärde, skrivna som ett JSX-attribut eller som en strängnyckel i ett attributobjekt, måste ange befintliga hanterare och sökvägar i lagret (blockstudio.interactivity.handler, blockstudio.interactivity.binding), och lagerkod får inte ändra attributen och klasserna som de binder till (blockstudio.interactivity.derivedState). React escape:ar attributvärden, så data-wp-context i en komponent rapporteras inte, och dynamiska värden kontrolleras inte. Namnrymder under bsui/ tillhör de medföljande UI-blocken, vars lager levereras med Blockstudio utanför de analyserade rötterna, så de är aldrig föräldralösa.

Diagnostikidentifierare

Ny diagnostik för förinställningar behåller stabila blockstudio.*-ID:n:

  • Temastruktur: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Resurser och fält: 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
  • Interaktivitet: 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

Prestanda

Skannern hanterar vanliga kataloger som materialiserats på disk, tar bort dubbletter bland rötter, hoppar över beroende-, bygg- och cacheträd, cachar filläsningar i minnet och sorterar diagnostik deterministiskt. Håll rötterna snäva, undanta testdata och genererade träd och ange en filgräns för stora repositorier. JavaScript och Tailwind kan inaktiveras oberoende av varandra. Aktiv rendering körs aldrig om inte dess förinställning har valts.

Diagnostik för tema, JavaScript och Tailwind rapporteras via resultatcachen för PHPStan. Om du bara ändrar en block.json eller ett skript kan en varm cache rapportera det tidigare resultatet. Skicka --debug efter -- för att kringgå cachen när du verifierar sådana ändringar.

Projektavtal för kodningsagenter

Paketet installerar ett tredje körbart program, vendor/bin/blockstudio-agents. Det skriver ett AGENTS.md som beskriver projektet det körs i, vilket en kodningsagent behöver veta innan den ändrar något: vad projektet skapar, vilka Blockstudio-funktioner som är aktiverade, vad analysen kommer att avvisa och vilka kommandon som gäller.

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

Ingenting i utdata är en fast mall. Varje rad kommer från en av tre källor:

  • Projektets egna filer. Ett tema med ett style.css-huvud, block och filbaserade sidor ger ett annat dokument än ett tillägg som registrerar block och inget annat. Antal, kataloger, blocknamnrymder och mallspråk är det som skannern faktiskt hittade, med samma rötter och undantag som vid analysen.
  • blockstudio.json. Endast aktiverade funktioner beskrivs, med sina konfigurerade värden: prefix för blocktaggar och namnrymderna de slås upp i, Tailwind, den medföljande UI, återställning av redigerarresurser, cachesökvägen, prestandaprofilen, statisk prerendering och dess dynamiska sökvägar, temats standardvärden, Content Sync och commit-hooken.
  • Den valda phpstan.preset. Avsnittet om korrekthet läses från själva förinställningsfilerna, lager för lager, så att det listar exakt de regler som förinställningen registrerar. Vid base beskriver det reglerna för schema, mallar, hookar och inställningar. Vid extreme-theme beskriver det även reglerna för temastruktur, de strikta flaggorna PHPStan, osäkra PHP, utdataescaping, Tailwind och JavaScript. Om en regel läggs till i en förinställning uppdateras det genererade dokumentet i enlighet med detta.

Avsnittet om kommandon följer samma princip. wp bs prerender status visas när statisk prerendering är aktiverad, vendor/bin/blockstudio-githooks sync när githooks.commit är inställt och wp bs db schemas när projektet faktiskt har en db.php.

Alternativ Beteende
--root <path> Projektrot (standard: aktuell katalog)
--config <path> Sökväg till blockstudio.json (standard: <root>/blockstudio.json)
--output <path> Avtalssökväg (standard: <root>/AGENTS.md)
--stdout Skriv ut avtalet i stället för att skriva det till fil
--check Avsluta med 1 om avtalet på disk inte är aktuellt
--force Ersätt en fil som Blockstudio inte äger

--check gör avtalet till en CI-spärr, på samma sätt som commit-hooken gör analysen till en spärr:

Shell
vendor/bin/blockstudio-agents --check

Ägarskap

Den genererade filen har samma slags markör som den hanterade commit-hooken, och samma regel gäller: Blockstudio ersätter aldrig en fil som det inte har skrivit. En AGENTS.md som skapades innan kommandot, eller som en utvecklare skrev för hand, nekas med avslutningskod 2 och lämnas orörd tills --force skickas med.

Det är säkert att generera filen på nytt. Filen avslutas med ett anteckningsområde, och byten mellan markörerna bevaras vid varje ny generering:

Markdown
## Project notes

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

Avslutningskoderna är 0 när avtalet skrivs, är aktuellt eller skrivs ut, 1 när --check hittar ett inaktuellt avtal och 2 vid fel i användning, konfiguration eller filsystem.

Fälttypernas former

Tillägget mappar varje fälttyp i Blockstudio till en konkret typ i PHP:

Fälttyp PHP-typ
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (enkel) string|int
select, checkbox (flera) 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 (enkel) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (flera) list<array{id: int, url: string, ...}>
group Namngivna grupper använder understreck som prefix; anonyma grupper plattas ut i förälderns omfång
repeater list<array{...child fields...}>
tabs Plattas ut i förälderns omfång

API-stubbar

Tillägget innehåller stubbar för hela det offentliga 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()

Dessa ger komplettering och typkontroll utan att du behöver ha Blockstudio-tilläggets källkod på din dator.

Krav

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (rekommenderas för automatisk upptäckt)

Paketet installerar automatiskt sin BC Math-kompatibilitetsleverantör. Inbyggt ext-bcmath är därför valfritt, även för nyskapade teman som aktiverar kontrollerna för JavaScript via tema- eller extremförinställningen.