Zum Inhalt springen

Dennis · 23. Juli 2026

Blockstudio 7.5

Blockstudio 7.5 vervollständigt den dateiorientierten Workflow von Blockstudio: mit benutzerdefinierten Feldtypen, dateibasierten Site-Editor-Vorlagen, Block-Inseln, Storh-Datenbankspeicherung, logischen Erkennungsquellen, kombinierbaren Block-Tags sowie schnelleren Bereitstellungs- und Laufzeitpfaden.

Wiederverwendbare benutzerdefinierte Felder ermöglichen es Projekten bereits, eine Gruppe vorhandener Felder einmal zu definieren und mit type: "custom/{name}" wiederzuverwenden. Benutzerdefinierte Feldtypen lösen ein anderes Problem: Sie ermöglichen es einem Theme oder Plugin, einen neuen Feldtyp mit eigenem Namespace zu registrieren, ein eigenes Editor-Steuerelement bereitzustellen und den Wert als normale Blockstudio-Daten zu speichern.

Kurz gesagt:

  • Logische Discovery-Quellen: Runtimes können ein zusammengesetztes logisches Theme-Inventar einschließlich Herkunft und Cache-Identität bereitstellen, während Blockstudio die Zuständigkeit für Discovery, Geschwisterauflösung, generierte Assets, Canvas und Tailwind-Verhalten behält.
  • PHP-Feldtyp-Registry: Themes und Plugins können Namespaced-Feldtypen wie acme/dimensions mit bs_register_field_type() oder dem Filter blockstudio/field_types registrieren.
  • Editor-Steuerungs-Registry: Benutzerdefinierte Editor-Skripte können window.blockstudio.registerFieldType() aufrufen und die passende React-Steuerung im regulären Feld-Blockstudio UI rendern.
  • Strukturierte Werte: Benutzerdefinierte Felder können Zeichenfolgen, Zahlen, boolesche Werte, Arrays oder Objekte speichern, ohne Objektwerte durch die Normalisierung von Optionsfeldern umzuwandeln.
  • Speicherunterstützung: Benutzerdefinierte Felder auf Basis von Post-Meta und Optionen können ihren Werttyp und ihr REST-Schema deklarieren, einschließlich Objekt- und Arraywerten.
  • Native Integration: Benutzerdefinierte Feldtypen funktionieren in Gruppen, Tabs, Repeatern, wiederverwendbaren benutzerdefinierten Feldern, Templates und Template-Pfaden von Erweiterungen.
  • Site-Editor-Templates: Themes können wp_template– und wp_template_part-Quellen aus template.json-, part.json– und Blockstudio-Template-Dateien definieren.
  • Block-Inseln: Blöcke können zuerst ein cache-sicheres Grundgerüst rendern und nach dem Laden der Seite anfragespezifische Fragmente nachladen oder gebündelt abrufen.
  • Storh-Datenbankspeicher: bs.db kann einen indexierten Dateispeicher mit einem Datensatz pro Datei in Uploads verwenden. Öffentliche Ganzzahl-IDs bleiben erhalten; die Migration von JSONC zu Storh erfolgt über WP-CLI.
  • Verbesserungen an Parser und bsui: Zugeordnete Richtext-Absätze benötigen weniger eigene Parser-Anbindung, InnerBlocks kann tokenisiertes allowedBlocks verwenden, verschachtelte bs_render_block()-Ausgaben entsprechen in Editor-Vorschauen dem Frontend-Rendering, und bsui/button erhält Icons sowie einfachere Styling-Hooks.
  • Kombinierbare Block-Tags: Präfix-Tags können über ein anderes Präfix aufgelöst werden (<theme-ui-input> zu bsui/input), und Präfix- sowie Alias-Tags werden auch in der Block-Template-Ausgabe gerendert, nicht nur im Seiteninhalt.
  • Host-sichere Build-Caches: Runtime- und Editor-Caches liegen standardmäßig außerhalb von Uploads, unterstützen konfigurierbare Speicherorte und entfernen veraltete Einträge, damit sich in lang laufenden Projekten keine Cache-Dateien ansammeln.
  • Inkrementeller Seitenabgleich: Deployment-Tools können das vollständige Datei-Seiteninventar abgleichen, unveränderte Beiträge überspringen, Änderungen genau melden und nach der Aktivierung eine verifizierte Quellidentität speichern.
  • Schnelleres Rendering bei warmem Cache: Gültige Runtime-Caches werden vor der Discovery geladen, gleichzeitige Anfragen bei kaltem Cache veröffentlichen ein einziges atomares Ergebnis, und Tailwind behält einen Cache in Website-Größe samt wiederverwendbarem Compiler-Zustand.
  • Sicheres Rendering in Stapeln: Exporteure können den anfragebezogenen Render-Zustand zwischen Dokumenten zurücksetzen, ohne die Discovery neu aufzubauen, und beim Rendern von Blöcken Quelldatei-Abhängigkeiten erfassen.

Neue Funktionen

7.5 bringt zahlreiche neue Funktionen für Discovery, Templates und Speicher mit.

Logische Discovery-Quellen

Blockstudio entdeckt Dateien normalerweise in physischen Theme-Verzeichnissen. 7.5 ergänzt eine Quelle auf niedrigerer Ebene, API, für Runtimes, die ein Theme aus Overlays, Vorschauen, generierten Dateien, Remote-Mounts oder anderen zusammengesetzten Inventaren erstellen.

Eine Integration kann einen fertigen logischen Dateibaum bereitstellen, während Blockstudio weiterhin für Blöcke, Felder, Seiten, Patterns, den Site Editor, Canvas, Assets und das Tailwind-Verhalten zuständig ist:

PHP
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => ['layer' => 'parent'],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => ['layer' => 'preview'],
                    ],
                ],
                'preview-fingerprint'
            ),
        ];
    },
    10,
    2
);

Logische Pfade bleiben stabil, selbst wenn Geschwisterdateien aus verschiedenen physischen Verzeichnissen stammen. Quell-IDs und Fingerprints fließen in die Identitäten von Runtime- und Tailwind-Caches ein; überwachte Eingaben machen diese ungültig, und die Herkunft legt fest, wohin generierte Dateien geschrieben werden dürfen. Die standardmäßige Dateisystemquelle bleibt für normale Themes unverändert.

Datei-basierte Site-Editor-Templates

Teams können Inhaltsstrukturen bereits für Seiten und Patterns in Dateien verwalten. 7.5 erweitert dieses Modell auf den Site Editor selbst.

Text
theme/
  templates/
    front-page/
      template.json
      index.php
  parts/
    header/
      part.json
      index.php
JSON
{
  "slug": "front-page",
  "title": "Front Page"
}
PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <block name="core/post-content" />
  </main>
</div>

Blockstudio kompiliert die Quelle mit demselben Parser wie für Seiten und Patterns und stellt das Ergebnis WordPress als reguläres Site-Editor-Template oder Template-Teil bereit. Der Site Editor zeigt das Template an, das Frontend kann es rendern, und WordPress verwaltet weiterhin die Anpassungen.

Der letzte Punkt ist wichtig. Datei-basierte Templates dienen als Quell-Fallback. Wenn jemand ein Template im Site Editor speichert, erstellt WordPress die übliche Datenbankanpassung in wp_template oder wp_template_part, und diese Version hat Vorrang. Setze die Anpassung zurück, wird wieder die aktuelle Dateiquelle angezeigt.

Inkrementelles Seiten-Deployment

Datei-basierte Seiten erhielten in 7.5 einen Deployment-Abgleich über API. Seit 7.6.2 sind dieses explizite API und wp bs pages sync die einzigen Synchronisierungseinstiegspunkte; gewöhnliche Anfragen wenden keine Quelländerungen an:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

Der Durchlauf ermittelt das vollständige gewünschte Seiteninventar, vergleicht Inhalte und Fingerprints der Sync-Engine und meldet erstellte, aktualisierte, unveränderte, entfernte und fehlgeschlagene Seiten. Bei Seiten mit identischen Fingerprints werden weder Beiträge noch Post-Meta geschrieben. Fehlende verwaltete Seiten werden nur entfernt, wenn die Discovery fehlerfrei abgeschlossen wurde.

Der Abgleich liefert eine deterministische Quellidentität zurück, kennzeichnet ein Deployment jedoch nicht als erfolgreich. Deployment-Tools speichern diese Identität erst, wenn die zugehörigen Dateien und Routen aktiv und verifiziert sind. Beim Bootstrap von regulärem WP-CLI werden zwischengespeicherte Collection-Post-Typen und Rewrite-Regeln registriert, ohne jede Seite zu entdecken und zu synchronisieren.

Block-Inseln

Die meisten Blockstudio-Blöcke werden serverseitig gerendert. Das passt gut zu WordPress, bringt aber ein bekanntes Cache-Problem mit sich: Ein personalisierter Block kann das Caching der ganzen Seite erschweren.

Block-Inseln setzen diese Grenze auf Blockebene.

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Eine dynamische Insel rendert in der ersten Antwort nur einen cache-sicheren Platzhalter. Anschließend sendet der Browser eine einzige gebündelte Anfrage für alle bereiten dynamischen Inseln auf der Seite, und Blockstudio rendert diese Fragmente im tatsächlichen Anfragekontext des Besuchers.

So kann ein Full-Page-Cache das Seitengrundgerüst speichern, während der Warenkorb-Zähler, Kontosteuerungen, zugriffsbeschränkte UI und andere benutzerspezifische Elemente aktuell bleiben.

PHP
<div class="cart-count-placeholder">Loading cart...</div>
PHP
<div class="cart-count">
  <?php echo esc_html(acme_cart_count()); ?>
</div>

Für Blöcke, die bereits cache-sicheres HTML rendern und nur ein Frontend-Mount-Signal benötigen, verwende eine hydrierte Insel:

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Hydrierte Inseln senden keine REST-Anfrage. Sie werden normal gerendert und erhalten im Frontend ein blockstudio:island:hydrate-Event.

Dynamische Inseln funktionieren auch über programmgesteuerte Render-Pfade:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

Und über Block-Tags:

HTML
<bs:acme-cart-count product-id="42" />

Der Endpunkt ist bewusst eng begrenzt. Er rendert nur registrierte Blockstudio-Blöcke, die dynamisch und ausdrücklich als dynamische Inseln markiert sind. Attribute werden anhand des Block-Schemas und der Zulassungsliste der Insel gefiltert; jede Markierung enthält eine Signatur, die von der ausliefernden WordPress-Website generiert wurde.

Storh-Datenbankspeicher

Die Datenbankschicht von Blockstudio unterstützt bereits Tabellen, SQLite, JSONC, Post-Meta und benutzerdefinierte Post-Typen. 7.5 ergänzt storage: "storh" für Projekte, die einen dateibasierten Speicher mit sichereren gleichzeitigen Schreibzugriffen und aus dem Schema abgeleiteten Indizes möchten, Live-Datensätze aber nicht neben Block-Quelldateien ablegen wollen.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Storh-Datensätze liegen in Uploads:

Text
wp-content/uploads/blockstudio/db/my-theme-my-block/default/

Die öffentliche API bleibt unverändert. bs.db(), REST und Db::get() liefern weiterhin ganzzahlige id-Werte zurück. Intern ordnet Blockstudio diese IDs den UUIDv7-Dokument-IDs von Storh zu, sodass vorhandener Client-Code nicht geändert werden muss.

Jedes deklarierte Schemafeld wird für Gleichheitsfilter indexiert; numerische und datumsähnliche Felder erhalten Bereichsindizes, und explizite Hinweise auf eindeutige Werte werden übernommen. Für Projekte, die mit JSONC-Seed-Dateien begonnen haben, lässt die neue Migration von CLI die Quelldatei unverändert und schreibt einen gleichwertigen Storh-Speicher:

Shell
wp bs db migrate my-theme/app subscribers --to=storh

So erhält JSONC eine klarere Rolle als einfaches, versionierbares Seed- und Konfigurationsformat, während Storh zum besseren standardmäßigen Datei-Backend für schreibbare Produktionsdaten wird.

Verbesserungen an Parser und bsui

7.5 rundet außerdem kleinere Funktionen ab, die bei Projekten mit stärkerer Nutzung dateibasierter Templates und gebündeltem UI zum Tragen kommen.

Beim Element-Mapping lässt sich nun der häufige Fall eines Richtext-Absatzes ohne eigenen Builder abdecken. Wenn <p> auf einen registrierten Nicht-Core-Blockstudio-Block mit einem Richtext-Attribut content abgebildet wird, wird einfacher innerer Text in dieses Attribut kopiert. Verschachtelte Tags und zugeordnete Kindelemente werden weiterhin als innere Blöcke geparst.

InnerBlocks akzeptiert in Templates tokenisiertes allowedBlocks:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

Unterstützte Tokens sind namespace/*, category:<slug> und @theme. Sie werden serverseitig erweitert, bevor der Editor das Template erhält; der Frontend-Render-Pfad bleibt dadurch unverändert.

Programmgesteuerte Einbettungen verhalten sich jetzt ebenfalls vorhersehbarer. bs_render_block() und bs_block() rendern eingebettete Blöcke nun als im Frontend aufgelöste HTML, auch wenn sie aus der Editor-Vorschau eines anderen Blocks aufgerufen werden. So gelangen keine rohen <RichText />– oder <InnerBlocks />-Pseudo-Komponenten verschachtelter Blöcke in das Vorschau-Markup.

Für gebündeltes UI unterstützt bsui/button jetzt ein icon-Attribut und iconPosition. Gebündelte Inline-Stile von bsui/* werden in einer @layer bsui-Cascade-Layer ausgegeben, und Button-Varianten lassen sich mit blockstudio/ui/button/variants-style sowie dem bestehenden Filter blockstudio/blocks/attributes erweitern.

Block-Tags lassen sich nun noch besser kombinieren. Ein Präfix kann über ein anderes Präfix aufgelöst werden. So wird <theme-ui-input /> mit dem Projektpräfix theme über dem Namespace-Präfix ui zu bsui/input aufgelöst. Registrierte Präfix- und Alias-Tags werden nun auch in der Block-Template-Ausgabe gerendert, nicht nur im Seiteninhalt. Ein Template kann sie somit direkt ausgeben, ohne bs_render_block() aufzurufen.

Benutzerdefinierte Block-Builder, die über blockstudio/block_tags/builders registriert wurden, werden beim Parsen von Tags und zugeordneten Elementen ebenfalls konsistent berücksichtigt. Explizite Renderer-Filter werden weiterhin danach ausgeführt und können den Builder überschreiben.

Schnellere Anfragen bei warmem Cache und Exporte

Runtime- und Editor-Caches liegen jetzt standardmäßig unter wp-content/blockstudio/cache statt in Uploads. Der Speicherort lässt sich über cache.path oder blockstudio/cache/dir ändern. So bleibt persistentes Caching auch auf Hosts verfügbar, die PHP-Payloads in Uploads blockieren. Runtime-, Editor-Asset- und Tailwind-Caches entfernen außerdem veraltete Einträge automatisch, damit sich auf der Festplatte in lang laufenden Projekten keine unbegrenzte Zahl von Cache-Dateien ansammelt.

Bei warmem Frontend-Cache laden Anfragen jetzt eine gültige Runtime-Registry, bevor Discovery-Quellen erstellt werden. Dadurch entfallen die rekursive Quellensuche, die Block-Erstellung, das Parsen von Feldern und wiederholte Durchläufe durch den Cache-Key-Baum. Produktions- und Staging-Anfragen vertrauen standardmäßig 20 Sekunden lang auf einen validierten Watch-Snapshot; lokale und Entwicklungsumgebungen prüfen weiterhin bei jeder Anfrage.

Bei kaltem Cache wird die Erstellung gebündelt ausgeführt: Eine Anfrage erstellt und veröffentlicht die Payload atomar, während gleichzeitige Anfragen auf das fertige Ergebnis warten. Tailwind behält standardmäßig bis zu 1.000 kompilierte Einträge 30 Tage lang und verwendet den bereits aufgewärmten Compiler-Erstellungszustand erneut. So muss ein Routensatz in Website-Größe nicht ständig einen winzigen Cache durchlaufen.

Exporteure mit langer Laufzeit können zwischen Dokumenten Blockstudio\Batch_Render::reset() aufrufen. Dadurch werden anfragebezogene Zähler, Assets, Inseln, Layouts und die Tailwind-Generierung zurückgesetzt, ohne die Discovery neu aufzubauen. Der Filter blockstudio/render/dependencies stellt die Template- und Asset-Pfade bereit, die jeder gerenderte Block verwendet, und ermöglicht so Abhängigkeitsgraphen.

Zuverlässigkeit und Kompatibilität

Mehrere Fehlerbehebungen runden die Version ab:

  • Über blockstudio/blocks/attributes geänderte Felddefinitionen steuern nun sowohl die Optionsvalidierung zur Render-Zeit als auch das Editor-Schema. Typisierte numerische und boolesche Optionswerte werden ebenfalls konsistent aufgelöst.
  • Editor-Block-Wrapper verwenden dieselben generierten Klassen wie Frontend-Renderings, und Canvas kann über den neuen Filter blockstudio/editor/canvas/body_class die konfigurierten Body-Klassen des Frontends übernehmen.
  • Content Sync validiert vor destruktiven Schreibvorgängen den vollständigen Quellplan, beschränkt Bereinigungen auf die konfigurierte Inhaltsmenge und meldet fehlgeschlagene Dateischreibvorgänge, ohne den Sync-Status des betreffenden Elements voranzuschreiben.
  • Composer-Pakete, die in aktiven Themes oder übergeordneten Themes als Symlinks eingebunden sind, finden Editor-Assets im öffentlichen Theme-URL.
  • Datei-basierte Seiten mit Schlüsseln behalten die vom Editor verwalteten Feldwerte Blockstudio bei, migrieren beim Sync die ältere verschachtelte Schlüsselform und akzeptieren den numerischen Wert null als gültigen Schlüssel.
  • Dynamische Inseln prüfen Signaturen vor Anfrage-Attributfiltern, ignorieren nicht signierten Anfragekontext, stellen angemeldete Besucher derselben Herkunft wieder her und vermeiden Cache-Kollisionen bei anonymen benutzerspezifischen Inhalten.
  • Rohe Markdown-Seitenendpunkte berücksichtigen nun die Sichtbarkeit von Beiträgen und den Passwortschutz.
  • Editor-Steuerungen verarbeiten leere Bedingungen, „Alle auswählen“-Werte von Kontrollkästchen, asynchrone Optionsaktualisierungen, dynamische Render-Reihenfolgen und den RichText- oder WYSIWYG-Zustand von Repeatern zuverlässiger.

Benutzerdefinierte Feldtypen

Mehr zu den oben eingeführten benutzerdefinierten Feldtypen.

Warum benutzerdefinierte Feldtypen?

Blockstudio sollte direkt nach der Installation nützlich sein, doch echte Projekte benötigen oft bereichsspezifische Steuerungen: Auswahlfelder für Abstands-Tokens, Farbrollen eines Designsystems, responsive Abmessungen, Icon-Quellen, Produktauswahl oder redaktionelle Steuerungen, die einem strukturierten Wert zugeordnet sind.

Vor 7.5 konnten solche Projekte entweder mehrere integrierte Felder kombinieren oder den Editor forken. 7.5 bietet einen unterstützten Mittelweg: Blockstudio verwaltet den Feldlebenszyklus und das Projekt die Steuerung.

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});
JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

Anschließend lässt sich das Feld in block.json wie ein natives Feld verwenden:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "bottom"],
        "default": {
          "top": "md",
          "bottom": "md"
        }
      }
    ]
  }
}

Reguläre Template-Werte

Der gespeicherte Wert ist in PHP, Twig und Blade wie jedes andere Blockstudio-Attribut verfügbar.

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Dieselben Objektpfade funktionieren auch in Templates von Erweiterungen:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Hinweise zur Kompatibilität

Vorhandene integrierte Feldtypen bleiben unverändert. Auch vorhandene wiederverwendbare custom/{name}-Feldgruppen bleiben unverändert. Namen benutzerdefinierter Feldtypen müssen kleingeschrieben und mit einem Namespace versehen sein, zum Beispiel acme/dimensions; die Namespaces custom/ und blockstudio/ sind reserviert.

Wenn PHP einen Feldtyp registriert, das zugehörige Editor-Skript aber nicht die passende Steuerung registriert, behält Blockstudio den gespeicherten Wert bei und zeigt im Editor einen nicht bearbeitbaren Hinweis an. Ist ein Feldtyp nicht in PHP registriert, lässt Blockstudio ihn aus den generierten WordPress-Attributen weg.

Wartungsupdate 7.5.1

7.5.1 behebt eine Warnung zur Umwandlung von Arrays in Zeichenfolgen, die beim Vorbereiten mehrerer Auswahlwerte für das Rendering ausgegeben wurde. Die gespeicherten und gerenderten Werte waren bereits korrekt, aber Debug-Protokolle konnten für jedes gerenderte Feld eine Warnung enthalten.

Das dazugehörige Update für blockstudio/phpstan v0.1.7 erkennt außerdem Felder in anonymen Gruppen in PHP, Twig, Blade und abgeleiteten Template-Attributformen. Bestehende Projekte können diese Paketkorrektur mit composer update blockstudio/phpstan übernehmen.