Gå til indhold

PHPStan

Udvidelsen blockstudio/phpstan tilføjer statisk analyse til Blockstudio-projekter. Den validerer blokskabeloner, skemafiler, stier til indstillinger og hooknavne under analysen, så fejl opdages, før de når kørselstidspunktet.

Installation

Shell
composer require --dev blockstudio/phpstan

Skabelontypning i 7.7 og de udvidede bloktagkontroller kræver blockstudio/phpstan 0.1.9 eller nyere og PHPStan 2.1.47 eller nyere. Opdater pakken separat fra pluginet:

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

Udvidelsen registreres automatisk via installationsprogrammet til udvidelser i PHPStan. Manuel konfiguration er ikke nødvendig.

Hvad den kontrollerer

Adgang til skabelonfelter

Når en PHP-fil ligger ved siden af en block.json, validerer udvidelsen hver $a['key']-adgang i forhold til blokkens deklarerede attributter.

PHP
<?php

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

Udvidelsen ved, at Blockstudio definerer $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview og ø-variablerne, før den inkluderer en skabelon. Derfor rapporteres direkte opslag som $a['title'] ikke som muligvis udefinerede, og typen for $a udledes fra block.json ved siden af skabelonen. Strukturen bevares ved indsnævring, så $a['label'] ?? '', isset( $a['cta']['target'] ) og $a['cta']['title'] !== null beholder de deklarerede felttyper; en skabelon, der tildeler $a selv, beholder den tildelte type. Tilføj ikke en /** @var array<string, mixed> $a */-docblock: Den erstatter strukturen med et åbent array.

Feltnøgler følger runtime-reglerne for udfoldning i Blockstudio. tabs og anonyme group-containere uden en id er kun til præsentation, så deres underfelter forbliver i det overordnede omfang. En navngiven gruppe føjer gruppens ID til underfelternes nøgler som præfiks:

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

Genbrugelige brugerdefinerede felter

Filbaserede custom/*-referencer udfoldes, før skabelonnøgler og arraystrukturer kontrolleres. Udvidelsen læser det tilsvarende field.json og anvender de samme regler for idStructure, overrides, indlejrede referencer, grupper, faner og gentagere 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 resulterende skabelonnøgler er title og hero_description. De genkendes i PHP, Twig, Blade, bloktags og udledte attributstrukturer.

Manglende, tvetydige, ugyldige eller cykliske filbaserede definitioner udløser en specifik blockstudio.customField.*-fejl. Afhængige nøglekontroller springes over for blokken, så én uafklaret definition ikke medfører en ny række falske fejl om ukendte felter.

Definitioner, der kun registreres ved kørselstidspunktet via filteret blockstudio/fields PHP, kan ikke udledes ved statisk analyse. Brug en field.json-definition, når feltet skal bidrage med skabelonnøgler, der kontrolleres statisk.

Adgang til Twig-skabeloner

Skabeloner for Twig scannes automatisk. Ingen annotation er nødvendig.

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

Adgang til Blade-skabeloner

Skabeloner for Blade scannes på samme måde.

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

Validering af bloktags

Bloktags valideres de steder, hvor Blockstudio læser dem: <bs:>– og <block>-tags, præfikstags konfigureret i blockTags.prefixes (såsom <acme-card>, der opløses i navnerækkefølge som ved kørsel), samt aliastags i PHP-, Twig- og Blade-blokskabeloner og i sidelayouts. Sidekilder under pages/ (index.php, index.html, index.twig, index.blade.php) kontrolleres også, herunder de HTML-elementer, som projektet knytter til blokke. De medfølgende UI-blokke genkendes, når ui.enabled er slået til.

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

En attribut accepteres, når blokken erklærer den som et felt (herunder brugerdefinerede felter og de felter, som et bloktypet felt videresender under sit idStructure), eller når Blockstudio videresender den til blokkens rodelement: data-*, aria-*, id, style, role, title, lang, dir, hidden og tabindex. I skabeloner videreføres alle html-*-attributter; i sidekilder angiver et html--præfiks kun én af de attributter, der videresendes. Alt andet, især en ikke-deklareret class, rapporteres, fordi Blockstudio gemmer den uden nogensinde at gengive den.

Runtime registrerer elementtilknytninger og tagaliaser i PHP-filtre, som statisk analyse ikke kan evaluere. Derfor læser analysen dem fra blockstudio.json. scanPhp kontrollerer også tags i andre PHP-filer i projektet, f.eks. komponentmarkup i moduler, uden at rapportere ukendte blokke 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
    }
  }
}

Et element knyttes til et bloknavn eller til regler, der afprøves i rækkefølge: Den første regel, hvis attribut findes på elementet, vinder, og et almindeligt bloknavn matcher altid. Elementer, som projektet ikke knytter til en blok, beholder deres kerneblok og kontrolleres ikke. Diagnostik bruger blockstudio.blockTag.unknown, blockstudio.blockTag.attribute og blockstudio.blockTag.class.

Typning af databaseposter

Db::get() returnerer en typet instans baseret på skemaet db.php. Poststrukturer udledes automatisk.

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

Obligatoriske felter kan ikke være null. Valgfrie felter er type|null. Et id-felt (int) er altid til stede. Den samme typning virker med den PHP-native Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field-byggersyntaks.

Validering af indstillingsstier

Stier til Settings::get() kontrolleres i forhold til det kendte indstillingsskema.

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

Validering af hooknavne

Hooknavne for Blockstudio-filtre og handlinger valideres.

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

Dynamiske indstillingshooks som blockstudio/settings/tailwind/enabled er altid tilladt. Hooks, der ikke tilhører blockstudio, ignoreres.

Skemavalidering

Udvidelsen validerer hver Blockstudio-skemafil i projektet.

block.json:

  • Manglende name-felt
  • Manglende felt type
  • Manglende id på værdifelter, der kræver det
  • Ukendte felttyper
  • Feltegenskaber, som felttypen ikke accepterer, f.eks. "translat" i stedet for "translate", med den nærmeste kendte egenskab som forslag
  • select/radio/checkbox uden options eller populate
  • Dublerede felt-id’er
  • Et tabs-felt inde i en repeater, enten direkte eller inde i en gruppe uden en id
  • Ugyldige pluginDependencies-deklarationer

Containerfelter som group og tabs samt custom/*-felthenvisninger kan udelade id, når de kun udfolder eller omslutter andre felter.

Feltegenskaber kontrolleres mod de egenskaber, som schemas/block.json erklærer for hver indbygget felttype, samt de egenskaber, som alle felter accepterer. Wrapper-specifikke egenskaber på custom/*-referencer og projektspecifikke navnerumsfelttyper er ikke omfattet af denne kontrol. Eksisterende validering af felttyper og brugerdefinerede referencer gælder stadig. Identifikatorerne er blockstudio.blockJson.property og blockstudio.fieldJson.property.

Dette kontrollerer egenskabsnavne, ikke kun deres værdier: minimized er gyldig på et gentagefelt, men rapporteres på et tekstfelt. Pluginets runtime-adfærd er uændret. Hvis et projekt bevidst knytter egne metadata til indbyggede felter, kan du undertrykke kun disse fund uden at deaktivere andre formkontroller:

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

Indbyggede felter i en genanvendelig field.json kontrolleres stadig, også når en custom/*-reference har egne wrapper-indstillinger. Udvidelsesfiler er uden for omfanget af denne diagnosticering af egenskabsnavne; udvidelsesspecifikke set-regler gælder stadig.

field.json (brugerdefinerede genbrugelige felter):

  • Manglende name
  • Manglende eller tom attributes
  • Ugyldige attributobjekter eller manglende felt-type
  • Manglende id på værdifelter, der kræver det
  • Ukendte felttyper
  • Feltegenskaber, som felttypen ikke accepterer
  • Et tabs-felt i et gentagefelt, direkte eller i en gruppe uden en id
  • Manglende, tvetydige, ugyldige eller cykliske indlejrede custom/*-referencer

Udvidelse JSON (blokudvidelser i extensions/):

  • Manglende name (målblok)
  • Manglende nøgle blockstudio
  • Manglende nøgle blockstudio.extend

page.json (filbaserede sider):

  • Mangler title
  • Mangler slug
  • Ugyldige postStatus-værdier

db.php:

  • Mangler fields-array
  • Ugyldige felttyper
  • Understøtter både ældre arrays og Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Ugyldige HTTP-metoder
  • Forkert public-værdi (skal være true, false eller 'open')
  • Understøtter både ældre arrays og attributterede objekter som returværdier

cron.php:

  • Mangler schedule for konfigurerede opgaver
  • Mangler callback for konfigurerede opgaver
  • Understøtter både ældre arrays og attributterede objekter som returværdier

blockstudio.json:

  • Genvejsbooleske værdier som "tailwind": true (skal bruge det indlejrede objektformat {"enabled": true, "config": ""})

Konfiguration

Udvidelsen finder som standard Blockstudio-filer i det analyserede projekt. Når et projekt bruger blokke eller genanvendelige felter fra et bibliotek uden for projektroden, skal bibliotekets sti tilføjes til blockstudioScanRoots. Stien scannes for både block.json– og field.json-definitioner, så eksterne bloktags og deres brugerdefinerede felter kan valideres sammen.

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

Brug PHPStans standardkonfiguration for excludePaths til at ignorere filer.

Analyseforudindstillinger

Den automatisk fundne udvidelse er fortsat det kompatible grundlag. Blockstudio 7.6 tilføjer lag, der kan tilvælges, uden at ændre eksisterende projekter:

Forudindstilling Funktion
base.neon Eksisterende analyse af skemaer, skabeloner, hooks, indstillinger og API.
theme.neon Grundlaget plus WordPress-temarødder, stilheadere, Blockstudio-aktiver, afgrænsning af selektorer, feltstandardværdier og repeatergrænser.
extreme-theme.neon Tema plus PHPStan max, usikker PHP, outputescaping, Tailwind, JavaScript og kontroller af Interactivity API.
wordpress-render.neon Ekstremt tema plus en live-renderingsprobe for WordPress, som kalderen angiver.

Installation af blockstudio/phpstan aktiverer kun basisudvidelsen. Medtag et frivilligt lag i en eksisterende PHPStan-konfiguration:

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

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

blockstudioThemeExcludePaths styrer temascaneren. PHPStans standardindstilling for excludePaths styrer analyse af PHP uafhængigt.

Den kanoniske kommandos indstilling phpstan.excludePaths i blockstudio.json (og dens --exclude-indstilling) konfigurerer begge lag. Relative mønstre fortolkes ud fra hver konfigureret rod, så poster som vendor/** begrænser analysen af PHPStan såvel som Blockstudios projektscanning.

Et mønster, der angiver en enkelt mappe, som _dist/** eller node_modules/**, udelukker mappen, uanset hvor den findes, ikke kun ved siden af temaroden. Et mønster med en skråstreg, som assets/*/docs/**, forbliver forankret til roden. Genererede blokaktiver ligger i en _dist-mappe i hver blok, så formatet med en enkelt mappe holder kompileret output ude af analysen.

Kanonisk kommando

Pakken installerer vendor/bin/blockstudio-phpstan som sit analyseprogram. Det bruger forudindstillingen base, medmindre projektet vælger en anden, så installation af pakken ikke i sig selv aktiverer tema- eller ekstremtema-lagene:

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

Forudindstillingerne inkluderer selv udvidelsen. Tilføj ikke phpstan/extension-installer til et projekt, der kører den kanoniske kommando: når installationsprogrammet er til stede, indlæses extension.neon to gange, og PHPStan stopper med “This file is included multiple times”, før noget analyseres.

Kommandoen indstiller som standard PHPStan til en hukommelsesgrænse på 1G, så Composer-administrerede WordPress-projekter ikke arver en typisk grænse på 128M CLI. Angiv en eksplicit PHPStan-indstilling efter -- for at tilsidesætte den, f.eks. -- --memory-limit=512M --no-progress.

Tag analyse i brug i et eksisterende projekt

Et projekt, der aldrig er blevet analyseret, vil som regel rapportere fund ved første kørsel. I stedet for at sænke forudindstillingen skal du generere en PHPStan-baseline og angive phpstan.configuration til en projektkonfiguration, der inkluderer den. Ny kode underlægges derefter den fulde forudindstilling, mens de registrerede fund ikke står i vejen:

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

Behold linjen level for forudindstillingerne base og theme. Den kanoniske kommando indstiller kun niveau max for dem, hvis ingen projektkonfiguration er inkluderet, og uden et niveau stopper PHPStan med “No rules detected”. Forudindstillingen extreme-theme indstiller selv niveau max.

Relative stier fortolkes ud fra blockstudio.json. Den kanoniske kommando og den administrerede commit-hook finder begge filen, så hooken blokerer nye fund uden at kræve, at efterslæbet først ryddes.

Behold standardindstillinger for kommandoer, der gælder hele projektet, i blockstudio.json:

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

Relative rødder fortolkes ud fra filen, der angiver dem. Eksplicitte værdier for CLI erstatter de tilsvarende værdier for JSON. Angiv --blockstudio-json path/to/project.json for en alternativ konfigurationskilde. Fejlformateret JSON, ikke-understøttede phpstan-nøgler, ugyldige værdier og en manglende eksplicit kilde medfører altid en fejl med afslutningskode 2.

Vælg en anden forudindstilling, medtag en projektkonfiguration, tilføj gentagne rødder og udelukkelser, eller bed PHPStan om JSON:

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

Wrapperen sammensætter konfigurationen i systemets midlertidige mappe og sletter den ved afslutning. Den skriver aldrig genereret konfiguration, baselines, hooks eller caches i det analyserede projekt. Kaldere kan stadig konfigurere PHPStans normale cache eksplicit.

Aftalen for afslutningskoder er:

  • 0 når analysen består
  • 1 når PHPStan rapporterer diagnosticeringer
  • 2 ved ugyldig brug, konfiguration eller proceskørsel

Administreret commit-hook

Aktivér den hook, der ejes af Blockstudio, i blockstudio.json for at gøre analysen af ekstremtemaet til en commit-kontrol i arkivet:

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

Synkronisér den efter installation af afhængigheder eller ændring af indstillingen:

Shell
vendor/bin/blockstudio-githooks sync

Kommandoen skriver sin genererede pre-commit-hook og ejerskabspost i Gits fællesmappe, indstiller core.hooksPath til den administrerede hookmappe og kæder sikkert den tidligere konfigurerede pre-commit-hook sammen med den. Gentagne synkroniseringer opdaterer kun den genererede fil, så pakkeopgraderinger er idempotente.

Indstil commit til false, fjern den, eller fjern blockstudio.json, og kør derefter sync for at gendanne den registrerede hooksti og kun slette filer, der ejes af Blockstudio. Du kan også køre:

Shell
vendor/bin/blockstudio-githooks remove

Filer, der ejes af brugeren, overskrives eller slettes aldrig. Hvis nogen ændrer core.hooksPath, efter at Blockstudio blev aktiveret, bevares den nyere indstilling ved fjernelse. Den genererede hook understøtter sammenkædede Git-arbejdstræer og stier med mellemrum ved at finde det aktive arkiv og projektrod ved commit-tidspunktet. Den kører den kanoniske kommando fra den rod, så det samme phpstan-objekt styrer interaktive kørsler og commits uden gentagne genererede argumenter.

Hooken kører kun vendor/bin/blockstudio-phpstan. Blockstudio kører ikke en formateringsfunktion, og hooken omskriver aldrig projektfiler. Manglende afhængigheder og analysefejl blokerer committen med en fejl, der forklarer, hvad der skal gøres.

Live-rendering af WordPress

Live-laget kræver et eksplicit valg. Kalderen ejer miljøet for WordPress og angiver et 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 .

Kommandoen kører uden en shell og skal udskrive ét JSON-objekt:

JSON
{"ok":true}

En probe kan rapportere en målrettet fejl:

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

Afslutninger uden nulstatus, timeouts, fejlformateret JSON og ok: false medfører blockstudio.wordpress.render.

blockstudio.javascript.domContract rapporterer en attributvælger for [data-*], som et script sender til querySelector(), querySelectorAll(), closest() eller matches(), når ingen analyserede markup-elementer har den attribut. Markup omfatter alle filer af typerne PHP, Twig, Blade og HTML samt alle React-.tsx– og .jsx-komponenter under de analyserede rødder, bortset fra de udelukkede stier. Komponenter parses: Attributnavne i JSX tæller med, og det samme gør strengnøglerne i objektliteraler, så et attributobjekt, der spredes på et element, opfylder vælgeren, mens klassenavne og andre attributværdier ikke gør.

Interactivity API-kontrollerne læser de samme React-komponenter. Et data-wp-interactive-navnerum på et JSX-element tæller som en skabelonreference for blockstudio.interactivity.orphan, og data-wp-*-direktiverne deri opløses i forhold til det nærmeste omsluttende navnerum eller et namespace::-præfiks i værdien. Direktiver med en statisk strengværdi, skrevet som en JSX-attribut eller som en strengnøgle i et attributobjekt, skal angive eksisterende store-handlere og stier (blockstudio.interactivity.handler, blockstudio.interactivity.binding), og store-kode må ikke ændre de attributter og klasser, som den binder til (blockstudio.interactivity.derivedState). React undslipper attributværdier, så data-wp-context i en komponent ikke rapporteres, og dynamiske værdier kontrolleres ikke. Navnerum under bsui/ tilhører de medfølgende UI-blokke, hvis stores følger med Blockstudio uden for de analyserede rødder, så de er aldrig forældreløse.

Diagnostikidentifikatorer

Ny diagnostik fra forudindstillingerne bevarer stabile blockstudio.*-ID’er:

  • Temastruktur: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Aktiver og felter: 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

Ydeevne

Scanneren accepterer almindelige mapper, fjerner dubletter blandt rødder, springer afhængigheds-, build- og cachetræer over, cacher fillæsninger i hukommelsen og sorterer diagnosticeringer på en entydig måde. Hold rødderne snævre, udeluk test- og genererede træer, og angiv en filgrænse for store arkiver. JavaScript og Tailwind kan deaktiveres uafhængigt af hinanden. Live-rendering kører aldrig, medmindre dens forudindstilling er valgt.

Temadiagnostik samt diagnosticeringer fra JavaScript og Tailwind rapporteres gennem resultatcachen i PHPStan. Hvis kun en block.json eller et script ændres, kan en varm cache vise det tidligere resultat. Angiv --debug efter -- for at omgå cachen, når du verificerer sådanne ændringer.

Projektaftale for kodeagenter

Pakken installerer et tredje program, vendor/bin/blockstudio-agents. Det skriver et AGENTS.md, der beskriver projektet, det køres i, og som kodeagenten skal kende, før den ændrer noget: hvad projektet udvikler, hvilke Blockstudio-funktioner der er aktiveret, hvad analysen afviser, og hvilke kommandoer der gælder.

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

Intet i outputtet er en fast skabelon. Hver linje stammer fra en af følgende tre kilder:

  • Projektets egne filer. Et tema med en style.css-header, blokke og filbaserede sider giver et andet dokument end et plugin, der kun registrerer blokke. Antal, mapper, bloknavnerum og skabelonsprog er det, scanneren faktisk fandt, ud fra de samme rødder og udelukkelser som analysen.
  • blockstudio.json. Kun aktiverede funktioner beskrives sammen med deres konfigurerede værdier: præfikser til bloktags og de navnerum, de slås op i, Tailwind, det medfølgende UI, nulstilling af editoraktiver, cachesti, ydelsesprofil, statisk forhåndsgengivelse og dens dynamiske stier, temastandarder, Content Sync og commit-hooken.
  • Den valgte phpstan.preset. Afsnittet om korrekthed læses fra selve forudindstillingsfilerne, lag for lag, så det viser præcis de regler, som forudindstillingen registrerer. Ved base beskrives regler for skemaer, skabeloner, hooks og indstillinger. Ved extreme-theme beskrives også regler for temastruktur, de strenge PHPStan-flag, usikker PHP, outputescaping, Tailwind og JavaScript. Når en regel føjes til en forudindstilling, afspejles det i det genererede dokument.

Afsnittet om kommandoer følger samme princip. wp bs prerender status vises, når statisk forhåndsgengivelse er aktiveret, vendor/bin/blockstudio-githooks sync når githooks.commit er indstillet, og wp bs db schemas når projektet faktisk har en db.php.

Indstilling Funktion
--root <path> Projektrod (standard: aktuel mappe)
--config <path> blockstudio.json-sti (standard: <root>/blockstudio.json)
--output <path> Aftalesti (standard: <root>/AGENTS.md)
--stdout Udskriv aftalen i stedet for at skrive den til en fil
--check Afslut med 1, hvis aftalen på disken ikke er opdateret
--force Erstat en fil, som Blockstudio ikke ejer

--check gør aftalen til en CI-kontrol, på samme måde som commit-hooken gør analysen til en:

Shell
vendor/bin/blockstudio-agents --check

Ejerskab

Den genererede fil har samme type markør som den administrerede commit-hook, og samme regel gælder: Blockstudio erstatter aldrig en fil, den ikke selv har skrevet. En AGENTS.md, der fandtes før kommandoen, eller som en forfatter har skrevet i hånden, afvises med afslutningskode 2 og forbliver urørt, indtil --force angives.

Det er sikkert at generere filen igen. Filen slutter med et noteafsnit, og bytes mellem markørerne bevares ved hver generering:

Markdown
## Project notes

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

Afslutningskoderne er 0, når aftalen skrives, er opdateret eller udskrives, 1 når --check finder en forældet aftale, og 2 ved fejl i brug, konfiguration eller filsystem.

Felttypers former

Udvidelsen knytter hver felttype i Blockstudio til en konkret PHP-type:

Felttype Type for PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (enkelt) string|int
select, checkbox (flere) 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 (enkelt) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (flere) list<array{id: int, url: string, ...}>
group Navngivne grupper bruger understregningspræfikser; anonyme grupper udflades i det overordnede omfang
repeater list<array{...child fields...}>
tabs Udfladet i det overordnede omfang

API-stubs

Udvidelsen indeholder stubs for hele den offentlige 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()

Disse giver autofuldførelse og typekontrol uden at kræve, at kilden til Blockstudio-plugin’et findes på din maskine.

Krav

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (anbefales til automatisk registrering)

Pakken installerer automatisk sin kompatibilitetsudbyder til BC Math. Indbygget ext-bcmath er derfor valgfrit, også for nye genererede temaer, der aktiverer JavaScript-kontrollerne via tema- eller ekstremforudindstillingen.