Zum Inhalt springen

PHPStan

Die Erweiterung blockstudio/phpstan bringt statische Analyse in Blockstudio-Projekte. Sie prüft Blockvorlagen, Schema-Dateien, Einstellungspfade und Hook-Namen während der Analyse und erkennt Fehler, bevor sie zur Laufzeit auftreten.

Installation

Shell
composer require --dev blockstudio/phpstan

Für die Vorlagen-Typisierung in 7.7 und die erweiterten Block-Tag-Prüfungen ist blockstudio/phpstan 0.1.9 oder neuer sowie PHPStan 2.1.47 oder neuer erforderlich. Aktualisiere das Paket getrennt vom Plugin:

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

Die Erweiterung wird automatisch über den Extension Installer von PHPStan erkannt. Eine manuelle Konfiguration ist nicht nötig.

Was geprüft wird

Zugriff auf Vorlagenfelder

Wenn eine Datei PHP neben einer Datei block.json liegt, prüft die Erweiterung jeden Zugriff auf $a['key'] anhand der deklarierten Attribute des Blocks.

PHP
<?php

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

Die Erweiterung weiß, dass Blockstudio $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview und die Island-Variablen definiert, bevor eine Vorlage eingebunden wird. Daher werden direkte Zugriffe wie $a['title'] nicht als möglicherweise undefiniert gemeldet, und $a erhält seinen Typ aus der neben der Vorlage liegenden block.json. Die Struktur bleibt beim Eingrenzen erhalten, sodass $a['label'] ?? '', isset( $a['cta']['target'] ) und $a['cta']['title'] !== null die deklarierten Feldtypen behalten; weist eine Vorlage $a selbst einen Wert zu, behält es den zugewiesenen Typ. Füge keinen /** @var array<string, mixed> $a */-Docblock hinzu: Er ersetzt diese Struktur durch ein offenes Array.

Feldschlüssel folgen den Regeln zur Laufzeitabflachung von Blockstudio. tabs und anonyme group-Container ohne id dienen nur der Darstellung, daher bleiben ihre untergeordneten Felder im übergeordneten Gültigkeitsbereich. Eine benannte Gruppe stellt ihren untergeordneten Schlüsseln die Gruppen-ID voran:

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

Wiederverwendbare benutzerdefinierte Felder

Dateibasierte Verweise auf custom/* werden aufgelöst, bevor Vorlagenschlüssel und Array-Strukturen geprüft werden. Die Erweiterung liest die passende field.json und wendet dieselben Regeln für idStructure, overrides, verschachtelte Verweise, Gruppen, Tabs und Repeater wie Blockstudio an:

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

Die resultierenden Vorlagenschlüssel sind title und hero_description. Sie werden in PHP, Twig, Blade, Block-Tags und abgeleiteten Attributstrukturen erkannt.

Fehlende, mehrdeutige, ungültige oder zyklische dateibasierte Definitionen erzeugen einen spezifischen Fehler blockstudio.customField.*. Die abhängigen Schlüsselprüfungen für diesen Block werden übersprungen, damit eine ungelöste Definition keine weiteren Fehlermeldungen zu unbekannten Feldern auslöst.

Definitionen, die nur zur Laufzeit über den Filter blockstudio/fields PHP registriert werden, lassen sich durch statische Analyse nicht ableiten. Verwende eine Definition field.json, wenn das Feld zu statisch geprüften Vorlagenschlüsseln beitragen muss.

Zugriff auf Twig-Vorlagen

Twig-Vorlagen werden automatisch durchsucht. Es ist keine Annotation erforderlich.

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

Zugriff auf Blade-Vorlagen

Blade-Vorlagen werden auf dieselbe Weise durchsucht.

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

Prüfung von Block-Tags

Block-Tags werden dort geprüft, wo Blockstudio sie einliest: bei den Tags <bs:> und <block>, den in blockTags.prefixes konfigurierten Präfix-Tags (wie <acme-card>, in Namensraum-Reihenfolge wie zur Laufzeit aufgelöst) und Alias-Tags – in Blockvorlagen für PHP, Twig und Blade sowie in Seitenlayouts. Auch Seitenquellen unter pages/ (index.php, index.html, index.twig, index.blade.php) werden geprüft, einschließlich der HTML-Elemente, die das Projekt Blöcken zuordnet. Integrierte UI-Blöcke werden erkannt, wenn ui.enabled aktiviert ist.

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

Ein Attribut wird akzeptiert, wenn der Block es als Feld deklariert (einschließlich benutzerdefinierter Felder und der Felder, die ein als Block typisiertes Feld über sein idStructure weiterleitet) oder wenn Blockstudio es an das Stammelement des Blocks weiterleitet: data-*, aria-*, id, style, role, title, lang, dir, hidden und tabindex. In Vorlagen werden alle Attribute html-* weitergeleitet; in Seitenquellen bezeichnet ein Präfix html- nur eines der weitergeleiteten Attribute. Alles andere wird gemeldet, vor allem ein nicht deklariertes class, weil Blockstudio es speichert, aber nie rendert.

Die Laufzeit registriert Elementzuordnungen und Tag-Aliase in PHP-Filtern, die von der statischen Analyse nicht ausgewertet werden können. Deshalb liest die Analyse sie aus blockstudio.json. scanPhp prüft Tags auch in anderen Projekt-PHP, etwa Komponenten-Markup in Modulen, ohne dort unbekannte Blöcke zu melden:

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

Ein Element wird einem Blocknamen oder einer Reihe von Regeln zugeordnet, die der Reihe nach geprüft werden: Es gilt die erste Regel, deren Attribut das Element trägt; ein einfacher Blockname passt immer. Elemente, denen das Projekt keine Zuordnung gibt, behalten ihren Core-Block und werden nicht geprüft. Diagnosemeldungen verwenden blockstudio.blockTag.unknown, blockstudio.blockTag.attribute und blockstudio.blockTag.class.

Typisierung von Datenbankeinträgen

Db::get() gibt eine typisierte Instanz auf Grundlage des db.php-Schemas zurück. Die Struktur der Datensätze wird automatisch abgeleitet.

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

Pflichtfelder sind nicht nullable. Optionale Felder sind type|null. Ein Feld id (int) ist immer vorhanden. Dieselbe Typisierung funktioniert auch mit der Builder-Syntax PHP-nativ Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Validierung von Einstellungspfaden

Pfade in Settings::get() werden anhand des bekannten Einstellungsschemas geprüft.

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

Validierung von Hook-Namen

Filter- und Action-Hook-Namen in Blockstudio werden geprüft.

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

Dynamische Einstellungshooks wie blockstudio/settings/tailwind/enabled sind immer zulässig. Hooks, die nicht zu Blockstudio gehören, werden ignoriert.

Schema-Validierung

Die Erweiterung prüft jede Blockstudio-Schema-Datei im Projekt.

block.json:

  • Fehlendes Feld name
  • Fehlendes Feld type
  • Fehlendes id bei Wertfeldern, die eines benötigen
  • Unbekannte Feldtypen
  • Feldeigenschaften, die der Feldtyp nicht akzeptiert, etwa "translat" statt "translate", mit der ähnlichsten bekannten Eigenschaft als Vorschlag
  • select/radio/checkbox ohne options oder populate
  • Doppelte Feld-IDs
  • Ein Feld vom Typ tabs in einem Repeater, direkt oder innerhalb einer Gruppe ohne id
  • Ungültige pluginDependencies-Deklarationen

Containerfelder wie group und tabs sowie Feldverweise custom/* können id weglassen, wenn sie ausschließlich andere Felder erweitern oder umschließen.

Feldeigenschaften werden mit den Eigenschaften verglichen, die schemas/block.json für jeden integrierten Feldtyp deklariert, sowie mit den Eigenschaften, die jedes Feld akzeptiert. Wrapper-spezifische Eigenschaften von custom/*-Referenzen und projektspezifisch definierte Namespaced-Feldtypen werden bei dieser Prüfung nicht berücksichtigt. Die bestehende Validierung von Feldtypen und benutzerdefinierten Referenzen gilt weiterhin. Die Bezeichner sind blockstudio.blockJson.property und blockstudio.fieldJson.property.

Hier werden Eigenschaftsnamen geprüft, nicht nur ihre Werte: minimized ist bei einem Repeater gültig, wird bei einem Textfeld aber beanstandet. Das Laufzeitverhalten des Plugins bleibt unverändert. Wenn ein Projekt seinen eigenen Metadaten bewusst zu integrierten Feldern hinzufügt, kannst du ausschließlich diese Befunde unterdrücken, ohne andere Formprüfungen zu deaktivieren:

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

In einem wiederverwendbaren field.json enthaltene integrierte Felder werden weiterhin geprüft, auch wenn eine custom/*-Referenz eigene Wrapper-Optionen hat. Erweiterungsdateien fallen nicht in den Geltungsbereich dieser Eigenschaftsnamen-Diagnosen; erweiterungsspezifische set-Regeln bleiben gültig.

field.json (wiederverwendbare benutzerdefinierte Felder):

  • name fehlt
  • attributes fehlt oder ist leer
  • Ungültige Attributobjekte oder fehlendes Feld-type
  • id fehlt bei Wertfeldern, die eines benötigen
  • Unbekannte Feldtypen
  • Feldeigenschaften, die der Feldtyp nicht akzeptiert
  • Ein tabs-Feld innerhalb eines Repeaters, direkt oder in einer Gruppe ohne id
  • Fehlende, mehrdeutige, ungültige oder zyklische verschachtelte custom/*-Referenzen

Erweiterung JSON (Blockerweiterungen in extensions/):

  • Fehlendes name (Zielblock)
  • Fehlender Schlüssel blockstudio
  • Fehlender Schlüssel blockstudio.extend

page.json (dateibasierte Seiten):

  • Fehlendes title
  • Fehlendes slug
  • Ungültige Werte für postStatus

db.php:

  • Fehlendes Array fields
  • Ungültige Feldtypen
  • Unterstützt sowohl ältere Arrays als auch Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Ungültige Methoden für HTTP
  • Falscher Wert für public (muss true, false oder 'open' sein)
  • Unterstützt sowohl ältere Arrays als auch Rückgaben attributierter Objekte

cron.php:

  • Fehlendes schedule bei konfigurierten Aufgaben
  • Fehlendes callback bei konfigurierten Aufgaben
  • Unterstützt sowohl ältere Arrays als auch Rückgaben attributierter Objekte

blockstudio.json:

  • Kurzform-Booleans wie "tailwind": true (es muss das verschachtelte Objektformat {"enabled": true, "config": ""} verwendet werden)

Konfiguration

Die Erweiterung erkennt standardmäßig Dateien Blockstudio im analysierten Projekt. Wenn ein Projekt Blöcke oder wiederverwendbare Felder aus einer Bibliothek außerhalb des Projektstammverzeichnisses nutzt, füge den Bibliothekspfad zu blockstudioScanRoots hinzu. Der Pfad wird nach Definitionen für block.json und field.json durchsucht, damit externe Block-Tags und ihre benutzerdefinierten Felder gemeinsam geprüft werden können.

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

Verwende die standardmäßige Konfiguration excludePaths von PHPStan, um Dateien zu ignorieren.

Analyse-Voreinstellungen

Die automatisch erkannte Erweiterung bleibt die kompatible Basis. Blockstudio 7.6 ergänzt optionale Ebenen, ohne bestehende Projekte zu verändern:

Voreinstellung Verhalten
base.neon Bestehende Schema-, Vorlagen-, Hook-, Einstellungs- und API-Analyse.
theme.neon Basis plus WordPress-Theme-Stammverzeichnisse, Style-Header, Blockstudio-Assets, Selektor-Eingrenzung, Feldstandards und Repeater-Grenzwerte.
extreme-theme.neon Theme plus PHPStan-max, unsicheres PHP, Ausgabe-Escaping, Tailwind, JavaScript und Prüfungen für Interactivity-API.
wordpress-render.neon Extreme Theme plus eine vom Aufrufer bereitgestellte Live-WordPress-Render-Prüfung.

Mit der Installation von blockstudio/phpstan wird nur die Basiserweiterung aktiviert. Füge eine optionale Ebene zu einer bestehenden PHPStan-Konfiguration hinzu:

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

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

blockstudioThemeExcludePaths steuert den Theme-Scanner. Die standardmäßige PHPStan-Einstellung excludePaths steuert unabhängig davon die Analyse von PHP.

Die Einstellung phpstan.excludePaths des kanonischen Befehls in blockstudio.json (und seine Option --exclude) konfiguriert beide Ebenen. Relative Muster werden anhand jedes konfigurierten Stammverzeichnisses aufgelöst. Einträge wie vendor/** begrenzen daher sowohl die PHPStan-Analyse als auch den Projektscan von Blockstudio.

Ein Muster für ein einzelnes Verzeichnis wie _dist/** oder node_modules/** schließt dieses Verzeichnis überall dort aus, wo es vorkommt, nicht nur neben dem Theme-Stammverzeichnis. Ein Muster mit Schrägstrich wie assets/*/docs/** bleibt am Stammverzeichnis verankert. Generierte Block-Assets liegen in einem Verzeichnis _dist innerhalb jedes Blocks. Daher hält die Form für einzelne Verzeichnisse kompilierte Ausgaben von der Analyse fern.

Kanonischer Befehl

Das Paket installiert vendor/bin/blockstudio-phpstan als ausführbare Datei für die Analyse. Es verwendet die Voreinstellung base, sofern ein Projekt keine andere auswählt. Die Installation des Pakets aktiviert daher nicht von selbst die Ebenen für Theme oder Extreme Theme:

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

Die Voreinstellungen enthalten die Erweiterung bereits. Füge phpstan/extension-installer nicht zu einem Projekt hinzu, das den kanonischen Befehl ausführt: Ist der Installer vorhanden, wird extension.neon zweimal geladen und PHPStan bricht mit „Diese Datei wird mehrfach eingebunden“ ab, bevor die Analyse beginnt.

Der Befehl setzt das PHPStan-Speicherlimit standardmäßig auf 1G, damit Composer-verwaltete WordPress-Projekte nicht das übliche 128M-CLI-Limit übernehmen. Übergib nach -- eine explizite PHPStan-Option, um es zu überschreiben, zum Beispiel -- --memory-limit=512M --no-progress.

Analyse in einem bestehenden Projekt einführen

Bei einem Projekt, das noch nie analysiert wurde, werden beim ersten Durchlauf in der Regel Befunde gemeldet. Statt die Voreinstellung herabzusetzen, erstelle eine PHPStan-Baseline und verweise phpstan.configuration auf eine Projektkonfiguration, die sie einbindet. Neuer Code wird dann anhand der vollständigen Voreinstellung geprüft, während die erfassten Befunde nicht im Weg stehen:

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

Behalte die level-Zeile für die Presets base und theme bei. Der kanonische Befehl setzt für sie nur dann Level max, wenn keine Projektkonfiguration eingebunden ist. Ohne Level gibt PHPStan „No rules detected“ aus. Das Preset extreme-theme setzt Level max selbst.

Relative Pfade werden ausgehend von blockstudio.json aufgelöst. Sowohl der kanonische Befehl als auch der verwaltete Commit-Hook berücksichtigen die Datei. Dadurch verhindert der Hook neue Befunde, ohne dass zuerst der Rückstand behoben werden muss.

Lege projektweite Standardwerte für Befehle in blockstudio.json fest:

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

Relative Stammverzeichnisse werden ausgehend von der Datei aufgelöst, in der sie angegeben sind. Explizite Werte für CLI ersetzen die entsprechenden Werte für JSON. Übergib --blockstudio-json path/to/project.json als alternative Konfigurationsquelle. Fehlerhaftes JSON, nicht unterstützte Schlüssel für phpstan, ungültige Werte und eine fehlende explizite Quelle führen deterministisch zum Exit-Code 2.

Wähle ein anderes Preset, binde eine Projektkonfiguration ein, füge wiederholt Stammverzeichnisse und Ausschlüsse hinzu oder frage PHPStan nach JSON:

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

Der Wrapper erstellt die Konfiguration im temporären Systemverzeichnis und löscht sie beim Beenden. Er schreibt weder generierte Konfigurationen noch Baselines, Hooks oder Caches in das analysierte Projekt. Den normalen Cache von PHPStan kannst du weiterhin explizit konfigurieren.

Die Exit-Codes sind:

  • 0, wenn die Analyse erfolgreich ist
  • 1, wenn PHPStan Diagnosen meldet
  • 2 bei ungültiger Verwendung, Konfiguration oder Prozessausführung

Verwalteter Commit-Hook

Aktiviere den von Blockstudio verwalteten Hook in blockstudio.json, damit die Analyse des Extreme-Themes als Commit-Prüfung für das Repository dient:

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

Synchronisiere ihn nach der Installation von Abhängigkeiten oder einer Änderung der Einstellung:

Shell
vendor/bin/blockstudio-githooks sync

Der Befehl schreibt den generierten Pre-Commit-Hook und den Eigentumsnachweis in Git’s gemeinsames Verzeichnis, setzt core.hooksPath auf das verwaltete Hook-Verzeichnis und bindet den zuvor konfigurierten Pre-Commit-Hook sicher ein. Wiederholte Synchronisierungen aktualisieren nur die generierte Datei, sodass Paket-Upgrades idempotent sind.

Setze commit auf false, entferne es oder entferne blockstudio.json. Führe anschließend sync aus, um den gespeicherten Hook-Pfad wiederherzustellen und nur die von Blockstudio verwalteten Dateien zu löschen. Du kannst auch Folgendes ausführen:

Shell
vendor/bin/blockstudio-githooks remove

Dateien, die Nutzern gehören, werden niemals überschrieben oder gelöscht. Wenn jemand core.hooksPath ändert, nachdem Blockstudio aktiviert wurde, bleibt diese neuere Einstellung beim Entfernen erhalten. Der generierte Hook unterstützt verknüpfte Git-Checkouts und Pfade mit Leerzeichen, indem er das aktive Repository und das Projektstammverzeichnis zum Commit-Zeitpunkt ermittelt. Er führt den kanonischen Befehl von diesem Stammverzeichnis aus aus. So steuert dasselbe Objekt phpstan sowohl interaktive Ausführungen als auch Commits, ohne dass generierte Argumente doppelt gepflegt werden müssen.

Der Hook führt ausschließlich vendor/bin/blockstudio-phpstan aus. Blockstudio führt keinen Formatter aus, und der Hook schreibt Projektdateien niemals um. Fehlende Abhängigkeiten und Analysefehler verhindern den Commit und geben eine hilfreiche Fehlermeldung aus.

Live-Rendering von WordPress

Die Live-Ebene ist bewusst explizit gehalten. Der Aufrufer ist für die WordPress-Umgebung verantwortlich und übergibt ein 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 .

Der Befehl wird ohne Shell ausgeführt und muss genau ein JSON-Objekt ausgeben:

JSON
{"ok":true}

Eine Prüfung kann einen gezielten Fehler melden:

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

Beenden mit einem Fehlercode, Zeitüberschreitungen, fehlerhaftes JSON und ok: false führen zu blockstudio.wordpress.render.

blockstudio.javascript.domContract meldet einen [data-*]-Attributselektor, den ein Skript an querySelector(), querySelectorAll(), closest() oder matches() übergibt, wenn kein untersuchtes Markup dieses Attribut enthält. Zum Markup gehören alle PHP-, Twig-, Blade- und HTML-Dateien sowie alle React-.tsx– und .jsx-Komponenten unter den untersuchten Wurzelverzeichnissen, abzüglich der ausgeschlossenen Pfade. Komponenten werden geparst: JSX-Attributnamen zählen ebenso wie String-Schlüssel von Objektliteralen. Daher erfüllt ein auf ein Element angewendetes Attributobjekt-Spread den Selektor, Klassennamen und andere Attributwerte hingegen nicht.

Die Interactivity-API-Prüfungen lesen dieselben React-Komponenten. Ein data-wp-interactive-Namespace auf einem JSX-Element zählt für blockstudio.interactivity.orphan als Vorlagenreferenz, und die darin enthaltenen data-wp-*-Direktiven werden anhand des nächstgelegenen umschließenden Namespace oder eines namespace::-Präfixes im Wert aufgelöst. Direktiven mit statischem Stringwert, angegeben als JSX-Attribut oder als String-Schlüssel eines Attributobjekts, müssen auf vorhandene Store-Handler und -Pfade verweisen (blockstudio.interactivity.handler, blockstudio.interactivity.binding), und Store-Code darf die Attribute und Klassen, an die er gebunden ist, nicht verändern (blockstudio.interactivity.derivedState). React maskiert Attributwerte, daher wird data-wp-context in einer Komponente nicht beanstandet; dynamische Werte werden ebenfalls nicht geprüft. Namespaces unter bsui/ gehören zu den mitgelieferten UI-Blöcken. Deren Stores werden zusammen mit Blockstudio außerhalb der untersuchten Wurzelverzeichnisse ausgeliefert, daher sind sie nie verwaist.

Diagnosekennungen

Neue Preset-Diagnosen behalten stabile blockstudio.*-IDs:

  • Theme-Struktur: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Assets und Felder: 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
  • Interaktivität: 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

Leistung

Der Scanner akzeptiert gewöhnliche Verzeichnisse, zählt Stammverzeichnisse nur einmal, überspringt Abhängigkeits-, Build- und Cache-Verzeichnisse, speichert Dateiinhalte im Arbeitsspeicher zwischen und sortiert Diagnosen deterministisch. Halte die Stammverzeichnisse eng gefasst, schließe Fixture- und generierte Verzeichnisse aus und lege für große Repositories ein Dateilimit fest. JavaScript und Tailwind lassen sich unabhängig voneinander deaktivieren. Live-Rendering wird nur ausgeführt, wenn das entsprechende Preset ausgewählt ist.

Diagnosen zu Themes, JavaScript und Tailwind werden über den Ergebniscache von PHPStan gemeldet. Wenn du nur ein block.json oder ein Skript änderst, kann ein warmer Cache das vorherige Ergebnis melden. Übergib --debug nach --, um den Cache bei der Überprüfung solcher Änderungen zu umgehen.

Projektvertrag für Coding-Agenten

Das Paket installiert ein drittes ausführbares Programm: vendor/bin/blockstudio-agents. Es schreibt eine AGENTS.md, die das Projekt beschreibt, in dem es ausgeführt wird. Diese braucht ein Coding-Agent, bevor er etwas ändert: welche Inhalte das Projekt erstellt, welche Blockstudio-Funktionen aktiviert sind, was die Analyse zurückweist und welche Befehle gelten.

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

Die Ausgabe basiert nicht auf einer festen Vorlage. Jede Zeile stammt aus einer von drei Quellen:

  • Dateien des Projekts. Ein Theme mit einem style.css-Header, Blöcken und dateibasierten Seiten erzeugt ein anderes Dokument als ein Plugin, das nur Blöcke registriert. Der Scanner ermittelt die Anzahl, Verzeichnisse, Block-Namespaces und Vorlagensprachen anhand derselben Stammverzeichnisse und Ausschlüsse wie bei der Analyse.
  • blockstudio.json. Beschrieben werden nur aktivierte Funktionen mit ihren konfigurierten Werten: Präfixe für Block-Tags und die Namespaces, über die sie aufgelöst werden, Tailwind, das gebündelte UI, das Zurücksetzen der Editor-Assets, der Cache-Pfad, das Leistungsprofil, statisches Prerendering und seine dynamischen Pfade, Theme-Standards, Content Sync und der Commit-Hook.
  • Das ausgewählte phpstan.preset. Der Abschnitt zur Korrektheit wird Ebene für Ebene direkt aus den Preset-Dateien gelesen. So werden genau die Regeln aufgelistet, die das Preset registriert. Bei base beschreibt er die Regeln für Schema, Vorlage, Hook und Einstellungen. Bei extreme-theme kommen außerdem die Regeln zur Theme-Struktur, die strikten PHPStan-Flags, unsicheres PHP, die Ausgabe-Escapierung, Tailwind und JavaScript hinzu. Wenn ein Preset eine Regel erhält, ändert sich auch das generierte Dokument.

Der Abschnitt zu den Befehlen folgt demselben Prinzip. wp bs prerender status erscheint, wenn statisches Prerendering aktiviert ist, vendor/bin/blockstudio-githooks sync, wenn githooks.commit festgelegt ist, und wp bs db schemas, wenn das Projekt tatsächlich ein db.php hat.

Option Verhalten
--root <path> Projektstammverzeichnis (Standard: aktuelles Verzeichnis)
--config <path> Pfad für blockstudio.json (Standard: <root>/blockstudio.json)
--output <path> Vertragspfad (Standard: <root>/AGENTS.md)
--stdout Vertrag ausgeben, statt ihn zu schreiben
--check Mit 1 beenden, wenn der Vertrag auf der Festplatte nicht aktuell ist
--force Eine Datei ersetzen, die Blockstudio nicht gehört

--check macht den Vertrag zu einer CI-Prüfung – genauso wie der Commit-Hook die Analyse zur Prüfung macht:

Shell
vendor/bin/blockstudio-agents --check

Eigentum

Die generierte Datei enthält denselben Markertyp wie der verwaltete Commit-Hook. Es gilt dieselbe Regel: Blockstudio ersetzt niemals eine Datei, die es nicht selbst geschrieben hat. Ein AGENTS.md, das bereits vor dem Befehl vorhanden war oder von einem Autor manuell erstellt wurde, wird mit Exit-Code 2 abgelehnt und bleibt unverändert, bis --force übergeben wird.

Die Datei lässt sich sicher neu generieren. Sie endet mit einem Notizbereich, dessen Inhalt zwischen den Markierungen bei jeder Neugenerierung unverändert bleibt:

Markdown
## Project notes

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

Die Exit-Codes sind 0, wenn der Vertrag geschrieben, aktuell oder ausgegeben wird, 1, wenn --check einen veralteten Vertrag erkennt, und 2 bei Fehlern mit der Verwendung, Konfiguration oder dem Dateisystem.

Feldtyp-Formen

Die Erweiterung ordnet jedem Blockstudio-Feldtyp einen konkreten PHP-Typ zu:

Feldtyp 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 (einzeln) string|int
select, checkbox (mehrere) 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 (einzeln) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (mehrere) list<array{id: int, url: string, ...}>
group Benannte Gruppen verwenden Unterstrich-Präfixe; anonyme Gruppen werden in den übergeordneten Bereich abgeflacht
repeater list<array{...child fields...}>
tabs In den übergeordneten Bereich abgeflacht

API-Stubs

Die Erweiterung enthält Stubs für das vollständige öffentliche 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()

Diese ermöglichen Autovervollständigung und Typprüfung, ohne dass du den Quellcode des Blockstudio-Plugins auf deinem Rechner benötigst.

Voraussetzungen

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (empfohlen für die automatische Erkennung)

Das Paket installiert seinen BC-Math-Kompatibilitätsanbieter automatisch. Native Unterstützung für ext-bcmath ist daher optional, auch bei neu generierten Themes, die die Prüfungen für JavaScript über das Theme- oder Extreme-Preset aktivieren.