WordPress Playground: Blueprints für Plugin-Vorschau und Tests

Die Schaltfläche „Preview“ auf einer WordPress.org-Pluginseite öffnet eine vorübergehende Testwebsite im Browser. PHP und Datenbank laufen dort mithilfe von WebAssembly. Eine Datei namens Blueprint beschreibt die Einrichtung: etwa die PHP-Version, benötigte Plugins und Demowerte. Dieselbe Datei lässt sich für die Verzeichnis-Vorschau, lokale Playground-Läufe und den Playground-Teil automatischer Tests verwenden.

Das Beispiel ergänzt Contact Form 7 um ein kleines Demonstrationsplugin. Eine zweite Teststrecke läuft mit Docker und wp-env. Diese Strecke verwendet eine eigene .wp-env.json und führt den Blueprint nicht aus. Der Unterschied ist sichtbar: Der Blueprint setzt eine Option auf 14, die reine Aktivierung ohne Blueprint auf 30. Der Beitrag zeigt diese zwei Wege und benennt genau, was die Tests prüfen. Die ursprünglichen Laufzeitbelege stammen vom 29.09.2026; Schema, Quellen und isolierte Prüfungen wurden am 25.10.2026 erneut abgeglichen.

Playground, Blueprints und die wichtigen Schritte

Im Browser benötigt Playground keinen eigenen PHP-Webserver. PHP läuft als WebAssembly, die Datenbank verwendet SQLite. Die Kommandozeilenfassung nutzt diese Laufzeit unter Node.js. Der hier verwendete Blueprint im Format V1 ist eine JSON-Datei: landingPage bestimmt die erste geöffnete Seite, preferredVersions enthält php und wp, und steps nennt die Einrichtungsschritte in Reihenfolge. features.networking wird im Beispiel ausdrücklich aktiviert. $schema verweist auf die Regeln, gegen die ein Editor die Datei prüfen kann.

Die unterstützten Versionen hängen vom jeweiligen Playground-Stand ab. Das aktuelle Schema akzeptiert unter anderem PHP 7.4 und 8.0 bis 8.5 sowie latest und next; zusätzlich existieren besondere Legacy-Einträge. Für den Beispielablauf sind konkrete Kombinationen wichtiger als eine dauerhafte Vollständigkeitsliste. Die Testmatrix nennt deshalb WordPress 6.7.9, 7.0.6 und 7.1.2. Das sind festgelegte Prüfstände, keine Aussage über die heute neueste Version.

Für die Einrichtung des Beispiels werden drei Schritte benötigt:

• installPlugin erwartet eine Ressource in pluginData, etwa {"resource": "wordpress.org/plugins", "slug": "contact-form-7"}, eine url auf eine ZIP-Datei oder einen Verweis vom Typ git:directory. Die Aktivierung steuert options.activate; der Schlüssel gehört in options, nicht in pluginData. Ohne diese Angabe gilt im Quellcode true.
• login braucht nur username, Standard ist admin. Das Feld password ist im Schema als veraltet markiert.
• setSiteOptions speichert die Werte aus options als WordPress-Optionen. Das Beispiel setzt damit den Website-Titel und den Demowert 14.

Weitere Schritte können PHP-Code ausführen, Sprachpakete installieren oder Einstellungen in wp-config.php setzen. Alte Beispiele enthalten noch pluginZipFile und phpExtensionBundles; das aktuelle Schema markiert diese Angaben als veraltet beziehungsweise nicht mehr verwendet. Bei Abhängigkeiten steht die Reihenfolge ausdrücklich in steps. Ein öffentlich erreichbarer Blueprint lässt sich über ?blueprint-url= öffnen; auch ein JSON-Fragment nach https://playground.wordpress.net/# ist möglich. Das Diagramm trennt den gemeinsamen Playground-Blueprint von der eigenen Docker-Konfiguration.

Der Blueprint für die Vorschau im Verzeichnis

Für eine öffentliche Vorschau braucht das Plugin eine gültige Datei unter assets/blueprints/blueprint.json im SVN-Verzeichnis. Zusätzlich muss ein Committer, also ein Konto mit Schreibrecht für dieses Plugin, die Vorschau unter „Advanced“ auf „public“ stellen. Davor ist „Test Preview“ nur für diese Konten sichtbar. Ein automatisch erzeugter Test-Blueprint kann als Ausgangspunkt dienen.

Der geprüfte Importcode übernimmt passende Blueprint-Dateien aus diesem Ordner bis zu 102.400 Byte je Datei und behält höchstens zehn. Für die normale Vorschau wird blueprint.json verwendet. Ungültiges JSON wird verworfen. Beim Beispielplugin ergänzt der Import die Installation des eigenen Slugs am Ende, falls kein passender Schritt vorhanden ist, und erzwingt die Aktivierung. Passende ZIP-Adressen von downloads.wordpress.org werden in Slug-Ressourcen umgeschrieben. Eine im Dateinamen enthaltene Versionsbindung kann dabei verloren gehen. Der Import ist somit keine unveränderte Weitergabe der Datei.

Der Blueprint installiert deshalb Contact Form 7 und setzt Demowerte, enthält aber keinen Download des eigenen Add-ons. Das Verzeichnis ergänzt diesen Download. Die lokale Playground-CLI bindet stattdessen den Arbeitsordner ein und aktiviert das Add-on nach den Blueprint-Schritten. Ein eigener Downloadschritt könnte bei einem unveröffentlichten Plugin scheitern oder mit der Standardoption overwrite den eingebundenen Arbeitsordner ersetzen. Der Docker-Weg verwendet unabhängig davon seine Pluginliste.

Im Git-Projekt liegt die Datei hier unter .wordpress-org/blueprints/blueprint.json. Dieser Ordnername ist eine Konvention des Beispiels. Erst der Releaseablauf kopiert die Datei nach assets/blueprints/ in SVN. Ein Punkt am Ordneranfang schließt Dateien nicht automatisch aus einer Plugin-ZIP aus; das Packskript muss den Ausschluss tatsächlich vornehmen.

{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/wp-admin/plugins.php",
	"preferredVersions": {
		"php": "8.3",
		"wp": "latest"
	},
	"features": {
		"networking": true
	},
	"steps": [
		{
			"step": "login",
			"username": "admin"
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "wordpress.org/plugins",
				"slug": "contact-form-7"
			},
			"options": {
				"activate": true
			}
		},
		{
			"step": "setSiteOptions",
			"options": {
				"blogname": "LW Form Archive Demo",
				"lw_form_archive_retention_days": 14
			}
		}
	]
}

Als Startseite dient die Pluginliste. Dort zeigt WordPress ab Version 6.5 die Beziehung zwischen dem Add-on und Contact Form 7. Das ältere Handbook-Beispiel enthält noch veraltete Blueprint-Felder und ältere Laufzeitversionen. Der hier gezeigte Blueprint verwendet pluginData und wurde gegen das am 25.10.2026 abgerufene Schema geprüft.

Requires Plugins: die Abhängigkeit erklären

Der Header Requires Plugins nennt seit WordPress 6.5 die benötigten Plugins. Erwartet werden durch Kommas getrennte WordPress.org-Slugs wie contact-form-7, keine Dateipfade. Ein Slug ist der kurze Verzeichnisname des Plugins. Ungültige Schreibweisen können aus der Abhängigkeitsliste fallen. Das folgende Add-on demonstriert nur diesen Header und eine gespeicherte Option. Trotz des Namens „Form Archive“ archiviert der Code keine Formulare und löscht auch keine Daten nach der angegebenen Tageszahl.

<?php
/**
 * Plugin Name:       LW Form Archive
 * Description:       Example add-on for Contact Form 7 (dependency and Blueprint demo).
 * Version:           1.0.0
 * Requires at least: 6.7
 * Requires PHP:      7.4
 * Requires Plugins:  contact-form-7
 * Author:            Lukas Wojcik
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       lw-form-archive
 *
 * @package LW_Form_Archive
 */

defined( 'ABSPATH' ) || exit;

/**
 * Stores the default retention period on activation.
 *
 * add_option() leaves an existing value untouched, so a value that a
 * Blueprint wrote earlier with setSiteOptions survives activation.
 */
function lw_form_archive_activate() {
	add_option( 'lw_form_archive_retention_days', 30 );
}
register_activation_hook( __FILE__, 'lw_form_archive_activate' );

/**
 * Returns the retention period in days.
 *
 * @return int
 */
function lw_form_archive_retention_days() {
	return absint( get_option( 'lw_form_archive_retention_days', 30 ) );
}

Die Pluginverwaltung prüft Abhängigkeiten bei Installation und Aktivierung. Eine benötigte Erweiterung muss vor der Aktivierung des Add-ons vorhanden und aktiv sein. Die Oberfläche verhindert außerdem bestimmte Lösch- und Deaktivierungsschritte, solange abhängige Plugins betroffen wären. Das ist keine Dateisystemsperre: FTP kann Dateien weiterhin entfernen. Auch WP-CLI kann ein Plugin zunächst ohne Abhängigkeiten installieren; die anschließende Aktivierung kann dann scheitern.

Für diesen Ablauf ist activate_plugin() entscheidend. WordPress prüft dabei Anforderungen an WordPress, PHP und abhängige Plugins. Bei einem Fehler entsteht ein WP_Error. Playground prüft nach der Aktivierung, ob das Plugin tatsächlich aktiv ist. Fehlt Contact Form 7 oder verlangt die heruntergeladene Fassung eine neuere Umgebung, schlägt der Einrichtungslauf fehl. Ein erfolgreicher Lauf beweist dagegen zunächst nur, dass diese Einrichtung gelang.

add_option() lässt eine bereits gespeicherte Option unverändert. Deshalb bleiben die 14 Tage aus dem Blueprint erhalten; eine frische Installation ohne Blueprint erhält den Standardwert 30. Das sind Beispielwerte ohne nachgelagerte Löschfunktion. Ein eigener Beitrag dieser Reihe erläutert den Lebenszyklus. Der Abhängigkeitseintrag nennt weder Mindestversionen des anderen Plugins noch eine Ladereihenfolge. Code, der eine bestimmte Klasse oder Funktion benötigt, muss deren Verfügbarkeit zusätzlich prüfen.

Lokale Läufe mit der Playground CLI

Die Beispiele verwenden fest @wp-playground/cli@3.1.56, den Stand der dokumentierten ursprünglichen Tests. start bewahrt eine Entwicklungswebsite für spätere Aufrufe auf. server startet den lokalen Webzugang; run-blueprint führt die Einrichtung ohne dauerhaft laufenden Webserver aus. Daneben gibt es Export und einzelne PHP-Aufrufe. Frische Standardläufe eignen sich besser für vergleichbare Tests als eine bereits veränderte Entwicklungswebsite. Eingebundene Arbeitsordner bleiben allerdings echte lokale Dateien und werden dadurch nicht automatisch zurückgesetzt.

# Run from the plugin folder (the folder name must match the slug).
cd lw-form-archive

# Interactive: fresh site on http://127.0.0.1:9400 with the working copy mounted.
# PHP and WordPress come from preferredVersions in the Blueprint (8.3, latest);
# --php and --wp have no effect together with a Blueprint file (CLI 3.1.56).
npx @wp-playground/cli@3.1.56 server --auto-mount \
  --blueprint=.wordpress-org/blueprints/blueprint.json

# Smoke test on the oldest tested branch (patched release): a copy with other preferredVersions,
# run without a server, non-zero exit code on failure.
node -e "const fs = require('fs');
  const b = JSON.parse(fs.readFileSync('.wordpress-org/blueprints/blueprint.json', 'utf8'));
  b.preferredVersions = { php: '7.4', wp: '6.7.9' };
  fs.writeFileSync('/tmp/blueprint-min.json', JSON.stringify(b));"
npx @wp-playground/cli@3.1.56 run-blueprint --auto-mount \
  --blueprint=/tmp/blueprint-min.json

--auto-mount bindet ohne weiteren Wert den aktuellen Ordner ein. Die CLI erkennt den Plugin-Header und verwendet den Ordnernamen unter /wordpress/wp-content/plugins/. Nach den Blueprint-Schritten folgt die Aktivierung. Der Ordner heißt deshalb lw-form-archive, passend zum Plugin-Slug. Die Einbindung ist kein schreibgeschützter Schnappschuss; Tests gehören in eine entbehrliche Arbeitskopie.

Im dokumentierten Test mit CLI 3.1.56 hatten --wp und --php bei einer Blueprint-Datei nicht den erwarteten Vorrang. Tatsächlich liefen die Werte aus preferredVersions, obwohl eine Startmeldung andere Werte zeigte. Das Beispiel schreibt deshalb für jeden Test eine Kopie mit der gewünschten Kombination. Ein Fehler beendet run-blueprint mit einem Fehlerstatus. Dieser kurze Einrichtungstest prüft noch keine Formularverarbeitung. Für Browsertests über ?blueprint-url= braucht die Datei außerdem einen erreichbaren Speicherort und passende CORS-Freigaben für den Abruf.

wp-env: feste Versionen in Docker

Der zweite Weg verwendet @wordpress/env@11.16.0 mit Docker und MariaDB. Das ist besonders für Datenbankabfragen hilfreich, deren Verhalten von SQLite abweichen kann. .wp-env.json nennt die WordPress-Version, PHP und die zu installierenden Plugins. Die Variablen WP_ENV_CORE und WP_ENV_PHP_VERSION setzen in der Testmatrix andere Versionen. Der Blueprint wird dabei nicht geladen; Demowerte daraus fehlen also zunächst.

{
	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
	"core": "WordPress/WordPress#7.1.2",
	"phpVersion": "8.3",
	"plugins": [
		"https://downloads.wordpress.org/plugin/contact-form-7.6.1.7.zip",
		"."
	],
	"config": {
		"WP_DEBUG_LOG": true
	}
}

Im geprüften wp-env-Stand werden die Plugins in der angegebenen Reihenfolge aktiviert. Deshalb steht Contact Form 7 vor dem Add-on. Die versionierte ZIP-Adresse nennt hier 6.1.7. Der Parser entfernt die Versionsendung aus dem Dateinamen und erhält den erwarteten Ordner contact-form-7. Die Form .latest-stable.zip hat in diesem Parser ein anderes Ergebnis und ist daher kein gleichwertiger Ersatz. Die feste ZIP reduziert Änderungen an der Abhängigkeit, garantiert aber weder verfügbare Downloads noch identische Ergebnisse der gesamten Testumgebung.

WordPress/WordPress#7.1.2 bezeichnet ein genaues Tag im GitHub-Spiegel. Ein Tag 7.1 bezeichnet nicht automatisch 7.1.2. Innerhalb der Docker-Umgebung startet wp-env run cli einen angegebenen Befehl. Die alternative Playground-Laufzeit von wp-env verwendet SQLite und unterstützt laut aktueller Dokumentation den Befehl run nicht. Der folgende Workflow bleibt deshalb ausdrücklich beim Docker-Weg.

Eine CI-Matrix über WordPress- und PHP-Versionen

Eine Testmatrix wiederholt einen Ablauf mit mehreren Kombinationen. Hier verwenden beide Jobs genau WordPress 6.7.9/PHP 7.4, WordPress 7.0.6/PHP 8.2 und WordPress 7.1.2/PHP 8.4. Die erste Zeile prüft einen gepflegten Stand des ältesten ausgewählten Zweigs, nicht jede frühere 6.7-Ausgabe. Die Playground-Werte werden in eine Blueprint-Kopie geschrieben; wp-env erhält dieselben Versionsnummern über Umgebungsvariablen. Die Action-Tags v7 und Node 24 sind im Beispiel ausdrücklich angegeben.

# .github/workflows/compatibility.yml
name: Compatibility

on:
  push:
    branches: [ trunk ]
  pull_request:

permissions:
  contents: read

jobs:
  playground:
    name: Playground / WP ${{ matrix.wp }} / PHP ${{ matrix.php }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - { wp: '6.7.9', php: '7.4' }
          - { wp: '7.0.6', php: '8.2' }
          - { wp: '7.1.2', php: '8.4' }
    steps:
      # Check out into a folder named like the slug: auto-mount uses the folder name.
      - uses: actions/checkout@v7
        with:
          path: lw-form-archive
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      # For a Blueprint file the CLI ignores --wp and --php (CLI 3.1.56),
      # so the matrix versions go into preferredVersions of a copy.
      - name: Write the matrix versions into a copy of the Blueprint
        working-directory: lw-form-archive
        run: >-
          node -e "const fs = require('fs');
          const b = JSON.parse(fs.readFileSync('.wordpress-org/blueprints/blueprint.json', 'utf8'));
          b.preferredVersions = { php: '${{ matrix.php }}', wp: '${{ matrix.wp }}' };
          fs.writeFileSync(process.env.RUNNER_TEMP + '/blueprint.json', JSON.stringify(b));"
      - name: Run the Blueprint against the working copy
        working-directory: lw-form-archive
        run: >-
          npx --yes @wp-playground/cli@3.1.56 run-blueprint
          --auto-mount
          --blueprint=${{ runner.temp }}/blueprint.json

  wp-env:
    name: wp-env / WP ${{ matrix.wp }} / PHP ${{ matrix.php }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - { wp: '6.7.9', php: '7.4' }
          - { wp: '7.0.6', php: '8.2' }
          - { wp: '7.1.2', php: '8.4' }
    env:
      # Override core and phpVersion from .wp-env.json for this matrix cell.
      WP_ENV_CORE: WordPress/WordPress#${{ matrix.wp }}
      WP_ENV_PHP_VERSION: ${{ matrix.php }}
    steps:
      - uses: actions/checkout@v7
        with:
          path: lw-form-archive
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - name: Install wp-env
        run: npm install -g @wordpress/env@11.16.0
      - name: Start WordPress (activates the plugins from .wp-env.json)
        working-directory: lw-form-archive
        run: wp-env start
      - name: Check activation and the default option
        working-directory: lw-form-archive
        run: |
          wp-env run cli wp plugin is-active contact-form-7
          wp-env run cli wp plugin is-active lw-form-archive
          wp-env run cli wp eval 'if (lw_form_archive_retention_days() !== 30) { WP_CLI::error("Unexpected default retention value"); }'

Der Playground-Job prüft die Einrichtung mit der aktuell vom Pluginverzeichnis gelieferten stabilen Contact-Form-7-Fassung. Der Docker-Job verwendet dagegen die feste Fassung 6.1.7. Zusätzlich kontrolliert dieser Job, ob beide Plugins aktiv sind und die Funktion des Beispiels den Standardwert 30 liefert. wp plugin is-active meldet bei einem inaktiven Plugin einen Fehlerstatus. Das ist eine gezielte Kontrolle von Aktivierung und Option, kein umfassender Funktionstest und keine Zusage gleichbleibender Ergebnisse.

Der historische Test zeigt den Nutzen der zwei Wege: Contact Form 7 6.1.7 lief mit den älteren Anforderungen, während der damalige Entwicklungsstand 6.2-rc höhere WordPress- und PHP-Versionen verlangte. Eine künftig ausgelieferte stabile Fassung mit höheren Anforderungen kann daher den Playground-Job scheitern lassen, obwohl der Docker-Job mit der älteren festen Abhängigkeit weiter funktioniert. Das Signal betrifft zunächst diese getesteten Kombinationen. Ob das eigentliche Add-on fachlich korrekt arbeitet, braucht zusätzliche Tests.

Eine PR-Vorschau kann zusätzlich über WordPress/action-wp-playground-pr-preview@v4 eingerichtet werden. Für echte PHPUnit-Tests muss im Projekt eine Testsuite vorliegen. Ein vollständiger Aufruf nennt auch das Programm, etwa wp-env run cli --env-cwd=wp-content/plugins/lw-form-archive phpunit. Nur Container und Arbeitsordner anzugeben führt noch keinen Test aus. Ein eigener Beitrag dieser Reihe behandelt die statische Prüfung mit Plugin Check.

Grenzen und offene Punkte

• Der historische Bericht dokumentiert drei erfolgreiche lokale Playground-Zellen mit CLI 3.1.56. Ein GitHub- oder Docker-Lauf wurde damals nicht belegt. Für die hier korrigierte Fassung wurden JSON, YAML, Shell- und PHP-Syntax, vier Blueprint-Kombinationen gegen das aktuelle Schema sowie die Optionswerte 14 und 30 mit isolierten Ersatzfunktionen geprüft. Die ergänzten Docker-Prüfschritte wurden nicht in einer echten WordPress-Umgebung ausgeführt.
• Playground nutzt SQLite. Plugins mit eigenen Tabellen oder handgeschriebenem SQL können sich anders verhalten als unter MySQL; für eigene Tabellen ist der wp-env-Job die aussagekräftigere Prüfung. Zum Thema passt der Beitrag über Leistungsgrenzen von wp_postmeta und eigene Tabellen.
• Das Schema lässt für Ressourcen vom Typ wordpress.org/plugins kein Feld version zu (nur resource und slug), und für einen einfachen Slug baut der Quellcode die Download-Adresse mit latest-stable. Ein Slug, der bereits auf .zip endet, etwa contact-form-7.6.1.7.zip, dient unverändert als Dateiname: Im Test mit Version 6.1.5 installierte die Playground CLI genau diese Version, und der Import des Verzeichnisses schreibt nur Ressourcen vom Typ url um. Ob die Vorschau im Verzeichnis diese Form annimmt, ist nicht geprüft.
• Feste Werkzeugversionen reduzieren Änderungen zwischen Testläufen. Action-Tags, Node-Versionen, Images, Downloads und externe Dienste können sich trotzdem ändern. Ein Paket-Lockfile und dokumentierte Laufzeitversionen verbessern die Nachvollziehbarkeit; eine garantierte Gleichheit aller Ergebnisse entsteht daraus nicht.
• Das Verzeichnis importiert bis zu zehn Blueprint-Dateien, verwendet aber nur blueprint.json. Mehrere Dateien stellt das Handbook als möglichen späteren Schritt in Aussicht, ohne Termin.
• Der Ordnername .wordpress-org/blueprints/ und die Übertragung in die SVN-Assets sind Konventionen dieses Beitrags; den SVN-Aufbau selbst behandelt ein eigener Beitrag dieser Reihe.