WordPress Playground: Blueprint do podglądu wtyczki i testów

Przycisk „Preview” na stronie wtyczki w WordPress.org otwiera tymczasową witrynę testową w przeglądarce. PHP i baza danych działają dzięki WebAssembly. Plik o nazwie Blueprint opisuje konfigurację: na przykład wersję PHP, wymagane wtyczki i dane demonstracyjne. Ten sam plik może służyć do podglądu w katalogu, lokalnych uruchomień Playground i części automatycznych testów korzystającej z Playground.

Przykład dodaje do Contact Form 7 małą wtyczkę demonstracyjną. Druga ścieżka testowa korzysta z Dockera i wp-env. Ma własny plik .wp-env.json i nie wykonuje Blueprintu. Różnica jest widoczna: Blueprint ustawia opcję na 14, a aktywacja bez Blueprintu na 30. Artykuł rozdziela te dwie ścieżki i dokładnie opisuje zakres testów. Pierwotne wyniki uruchomień pochodzą z 29.09.2026; schemat, źródła i izolowane kontrole sprawdzono ponownie 25.10.2026.

Playground, Blueprinty i najważniejsze kroki

Playground w przeglądarce nie potrzebuje osobnego serwera WWW z PHP. PHP działa jako WebAssembly, a baza korzysta z SQLite. Wersja wiersza poleceń używa tego środowiska pod Node.js. Przedstawiony Blueprint w formacie V1 jest plikiem JSON: landingPage wybiera pierwszą stronę, preferredVersions zawiera php i wp, a steps określa kolejność czynności. Przykład jawnie włącza features.networking. $schema wskazuje reguły, według których edytor może sprawdzić plik.

Obsługiwane wersje zależą od wydania Playground. Aktualny schemat przyjmuje między innymi PHP 7.4 i od 8.0 do 8.5 oraz latest i next; istnieją też specjalne wpisy dla starszych wersji. Dla przykładu ważniejsze są konkretne kombinacje niż rzekomo niezmienna pełna lista. Macierz podaje więc WordPressa 6.7.9, 7.0.6 i 7.1.2. To wybrane wersje testowe, a nie informacja o najnowszym obecnie wydaniu.

Konfiguracja przykładu wymaga trzech kroków:

• installPlugin przyjmuje zasób w pluginData, na przykład {"resource": "wordpress.org/plugins", "slug": "contact-form-7"}, adres url do pliku ZIP albo odwołanie typu git:directory. Aktywacją steruje options.activate; klucz należy umieścić w options, a nie w pluginData. Gdy go brak, kod źródłowy przyjmuje true.
• login potrzebuje tylko username, domyślnie admin. Pole password jest w schemacie oznaczone jako przestarzałe.
• setSiteOptions zapisuje wartości z options jako opcje WordPressa. Przykład ustawia tytuł witryny i wartość demonstracyjną 14.

Inne kroki mogą wykonywać PHP, instalować pakiety językowe lub ustawiać wartości w wp-config.php. Starsze przykłady zawierają pluginZipFile i phpExtensionBundles; aktualny schemat oznacza te pola jako przestarzałe lub nieużywane. Kolejność zależności jest zapisana jawnie w steps. Publicznie dostępny Blueprint można otworzyć przez ?blueprint-url=; inną możliwością jest fragment JSON po https://playground.wordpress.net/#. Diagram oddziela wspólny Blueprint Playground od osobnej konfiguracji Dockera.

Blueprint dla podglądu w katalogu

Publiczny podgląd wymaga poprawnego pliku assets/blueprints/blueprint.json w katalogu SVN. Commiter, czyli konto z prawem zapisu do repozytorium tej wtyczki, musi dodatkowo ustawić podgląd na „public” w sekcji „Advanced”. Wcześniej „Test Preview” jest widoczne tylko dla takich kont. Automatycznie wygenerowany Blueprint testowy może służyć jako punkt wyjścia.

Sprawdzony importer przyjmuje pasujące pliki Blueprint z tego folderu, do 102 400 bajtów każdy, i zachowuje najwyżej dziesięć. Zwykły podgląd używa blueprint.json. Niepoprawny JSON jest odrzucany. Dla przykładowej wtyczki importer dopisuje na końcu instalację własnego sluga, jeśli brakuje odpowiedniego kroku, i wymusza aktywację. Pasujące adresy ZIP z downloads.wordpress.org zamienia na zasoby ze slugiem. Wersja wskazana w nazwie pliku może więc zostać utracona. Import nie przekazuje pliku bez zmian.

Blueprint instaluje zatem Contact Form 7 i ustawia dane demonstracyjne, ale nie pobiera samego dodatku. Katalog dopisuje takie pobranie. Lokalna wersja Playground CLI zamiast tego montuje folder roboczy i aktywuje dodatek po krokach Blueprintu. Osobny krok pobierania mógłby zawieść dla nieopublikowanej wtyczki albo zastąpić zamontowany folder przez domyślną opcję overwrite. Ścieżka Dockera niezależnie korzysta z własnej listy wtyczek.

W projekcie Git plik znajduje się tutaj pod .wordpress-org/blueprints/blueprint.json. Nazwa folderu jest konwencją przykładu. Proces wydania kopiuje plik do assets/blueprints/ w SVN. Kropka na początku nazwy nie wyklucza automatycznie folderu z paczki ZIP wtyczki; proces pakowania musi rzeczywiście zastosować takie wykluczenie.

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

Stroną startową jest lista wtyczek. WordPress od wersji 6.5 pokazuje tam zależność między dodatkiem a Contact Form 7. Starszy przykład w Handbook zawiera przestarzałe pola Blueprintu i starsze wersje środowiska. Poniższy Blueprint używa pluginData i przeszedł kontrolę według schematu pobranego 25.10.2026.

Requires Plugins: deklaracja zależności

Od WordPressa 6.5 nagłówek Requires Plugins wymienia wymagane wtyczki. Oczekiwane są slugi WordPress.org rozdzielone przecinkami, na przykład contact-form-7, a nie ścieżki plików. Slug to krótki identyfikator katalogowy wtyczki. Błędny zapis może wypaść z listy zależności. Poniższy dodatek demonstruje wyłącznie ten nagłówek i zapisaną opcję. Mimo nazwy „Form Archive” kod nie archiwizuje formularzy ani nie usuwa danych po podanej liczbie dni.

<?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 ) );
}

Panel zarządzania wtyczkami sprawdza zależności podczas instalacji i aktywacji. Wymagana wtyczka musi być obecna i aktywna przed aktywacją dodatku. Interfejs blokuje też niektóre operacje usuwania i dezaktywacji, gdy dotyczą wtyczek potrzebnych innym dodatkom. Nie jest to jednak blokada plików: FTP nadal może usunąć zawartość folderu. WP-CLI również może najpierw zainstalować wtyczkę bez zależności; późniejsza aktywacja może wtedy zawieść.

Dla tego przebiegu istotna jest funkcja activate_plugin(). WordPress sprawdza wymagania dotyczące WordPressa, PHP i zależnych wtyczek. Błąd daje wynik WP_Error. Playground następnie sprawdza, czy wtyczka rzeczywiście stała się aktywna. Brak Contact Form 7 lub pobrana wersja wymagająca nowszego środowiska powoduje niepowodzenie konfiguracji. Poprawny przebieg dowodzi początkowo tylko powodzenia tej konfiguracji.

add_option() nie zmienia istniejącej opcji. Dlatego wartość 14 z Blueprintu pozostaje po aktywacji; świeża instalacja bez Blueprintu otrzymuje domyślnie 30. To wartości przykładowe bez powiązanej procedury usuwania danych. Osobny artykuł z tej serii wyjaśnia cykl życia. Nagłówek zależności nie podaje minimalnych wersji innych wtyczek ani kolejności ładowania. Kod wymagający konkretnej klasy lub funkcji musi dodatkowo sprawdzić dostępność.

Lokalne uruchomienia z Playground CLI

Przykłady wskazują stałą wersję @wp-playground/cli@3.1.56, używaną w udokumentowanych pierwotnych testach. start zachowuje witrynę deweloperską między uruchomieniami. server uruchamia lokalny dostęp przez WWW; run-blueprint wykonuje konfigurację bez stale działającego serwera. Dostępne są też eksport i pojedyncze wywołania PHP. Świeże domyślne uruchomienia łatwiej porównać niż już zmodyfikowaną witrynę. Zamontowane foldery robocze nadal zawierają prawdziwe lokalne pliki i nie są automatycznie przywracane.

# 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 bez dodatkowej wartości montuje bieżący folder. CLI rozpoznaje nagłówek wtyczki i używa nazwy folderu pod /wordpress/wp-content/plugins/. Aktywacja następuje po krokach Blueprintu. Dlatego folder ma nazwę lw-form-archive, zgodną ze slugiem. Montowanie nie tworzy kopii tylko do odczytu; testy powinny korzystać z tymczasowej kopii roboczej.

W udokumentowanym teście CLI 3.1.56 opcje --wp i --php nie miały oczekiwanego pierwszeństwa przy podaniu pliku Blueprint. Rzeczywiste środowisko korzystało z preferredVersions, mimo innych wartości w komunikacie startowym. Dlatego przykład zapisuje dla każdego testu kopię z właściwą kombinacją. Błąd konfiguracji kończy run-blueprint statusem błędu. Taki krótki test konfiguracji nie sprawdza jeszcze obsługi formularzy. Test w przeglądarce przez ?blueprint-url= wymaga też dostępnego pliku i odpowiedniej zgody CORS na pobranie.

wp-env: stałe wersje w Dockerze

Druga ścieżka używa @wordpress/env@11.16.0 z Dockerem i MariaDB. Przydaje się to przy zapytaniach, które mogą zachowywać się inaczej niż w SQLite. .wp-env.json podaje wersję WordPressa, PHP i wtyczki do instalacji. Zmienne WP_ENV_CORE i WP_ENV_PHP_VERSION przekazują wersje z macierzy. Blueprint nie jest ładowany, więc początkowo brakuje wartości demonstracyjnych z tego pliku.

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

Sprawdzona wersja wp-env aktywuje wtyczki w podanej kolejności. Contact Form 7 musi więc znaleźć się przed dodatkiem. Wersjonowany adres ZIP wskazuje 6.1.7. Parser usuwa końcówkę z wersją i otrzymuje oczekiwany folder contact-form-7. Postać .latest-stable.zip daje w tym parserze inny wynik i nie jest równoważnym zamiennikiem. Stały ZIP ogranicza zmiany zależności, ale nie gwarantuje dostępności pobierania ani identycznych wyników całego środowiska.

WordPress/WordPress#7.1.2 oznacza dokładny tag w lustrze GitHub. Tag 7.1 nie oznacza automatycznie 7.1.2. W Dockerze wp-env run cli uruchamia podane dalej polecenie. Alternatywne środowisko Playground używa SQLite i według aktualnej dokumentacji nie obsługuje run. Poniższy workflow pozostaje więc jawnie przy Dockerze.

Macierz CI dla wersji WordPressa i PHP

Macierz testowa powtarza przebieg dla kilku kombinacji. Oba zadania używają dokładnie WordPressa 6.7.9/PHP 7.4, WordPressa 7.0.6/PHP 8.2 oraz WordPressa 7.1.2/PHP 8.4. Pierwszy wiersz sprawdza wydanie z poprawkami najstarszej wybranej gałęzi, a nie każde wcześniejsze wydanie 6.7. Playground otrzymuje wartości w kopii Blueprintu; wp-env dostaje te same numery przez zmienne środowiskowe. Przykład jawnie podaje również tagi akcji v7 i Node 24.

# .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"); }'

Zadanie Playground sprawdza konfigurację ze stabilną wersją Contact Form 7 aktualnie dostarczaną przez katalog. Zadanie Dockera używa zamiast tego stałej wersji 6.1.7. Dodatkowo sprawdza aktywność obu wtyczek i wynik 30 z funkcji przykładu. wp plugin is-active zwraca status błędu dla nieaktywnej wtyczki. To celowane kontrole aktywacji i opcji, a nie pełny test funkcjonalny ani obietnica niezmiennych wyników.

Historyczne testy pokazują sens obu ścieżek: Contact Form 7 6.1.7 miało starsze wymagania, a ówczesna wersja rozwojowa 6.2-rc wymagała nowszego WordPressa i PHP. Przyszłe stabilne wydanie zależności z wyższymi wymaganiami może więc spowodować błąd zadania Playground, podczas gdy zadanie Dockera ze starszą stałą zależnością nadal zadziała. Sygnał dotyczy najpierw tych testowanych kombinacji. Poprawność działania samego dodatku wymaga dodatkowych testów.

Podgląd PR można dodatkowo skonfigurować przez WordPress/action-wp-playground-pr-preview@v4. Rzeczywiste testy PHPUnit wymagają zestawu testów w projekcie. Pełne wywołanie podaje także program, na przykład wp-env run cli --env-cwd=wp-content/plugins/lw-form-archive phpunit. Samo wskazanie kontenera i katalogu roboczego nie uruchamia testu. Osobny artykuł z tej serii omawia statyczne kontrole przez Plugin Check.

Ograniczenia i otwarte kwestie

• Historyczny raport dokumentuje trzy udane lokalne kombinacje Playground z CLI 3.1.56. Nie potwierdza przebiegu na GitHubie ani w Dockerze. Dla poprawionej wersji sprawdzono JSON, YAML, składnię powłoki i PHP, cztery kombinacje Blueprintu według aktualnego schematu oraz wartości opcji 14 i 30 z izolowanymi funkcjami zastępczymi. Dodanych kontroli Dockera nie wykonano w prawdziwym środowisku WordPressa.
• Playground używa SQLite. Wtyczki z własnymi tabelami lub ręcznie pisanym SQL mogą zachowywać się inaczej niż pod MySQL; przy własnych tabelach bardziej miarodajne jest zadanie wp-env. Do tematu pasuje artykuł o granicach wydajności wp_postmeta i własnych tabelach.
• Schemat nie dopuszcza pola version dla zasobów typu wordpress.org/plugins (tylko resource i slug), a dla zwykłego sluga kod źródłowy buduje adres pobierania z latest-stable. Slug zakończony już na .zip, na przykład contact-form-7.6.1.7.zip, służy bez zmian jako nazwa pliku: w teście z wersją 6.1.5 Playground CLI zainstalowało dokładnie tę wersję, a import do katalogu przepisuje wyłącznie zasoby typu url. Nie sprawdzono, czy podgląd w katalogu przyjmuje tę postać.
• Stałe wersje narzędzi ograniczają zmiany między przebiegami. Tagi akcji, wydania Node, obrazy, pobierane pliki i usługi zewnętrzne nadal mogą się zmieniać. Plik blokady pakietów oraz zapis faktycznych wersji ułatwiają odtworzenie warunków, ale nie gwarantują identycznych wyników.
• Katalog importuje do dziesięciu plików Blueprint, ale korzysta tylko z blueprint.json. Obsługę wielu plików Handbook zapowiada jako możliwy przyszły krok, bez terminu.
• Nazwa katalogu .wordpress-org/blueprints/ i przenoszenie pliku do zasobów SVN to konwencje tego artykułu; samą strukturę SVN opisuje osobny artykuł z tej serii.