Blueprints WordPress Playground

Aperçu

Un Blueprint est un fichier JSON qui configure de façon déclarative une instance WordPress Playground — installation de plugins/thèmes, configuration d'options, exécution de PHP/SQL, manipulation de fichiers, et plus.

Principe fondamental : Les Blueprints sont des déclarations JSON de confiance uniquement. Pas de JavaScript arbitraire. Ils fonctionnent sur le web, Node.js, et CLI.

Modèle de démarrage rapide

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

Propriétés de niveau supérieur

Toutes optionnelles. Seules les clés documentées sont autorisées — le schéma rejette les propriétés inconnues.

Valeurs de preferredVersions

• php : Majeure.mineure uniquement (ex. "8.3", "7.4"), ou "latest". Les versions patch comme "7.4.1" sont invalides. Consultez le schéma pour les versions actuellement supportées.
• wp : Versions majeures récentes (ex. "6.7", "6.8"), "latest", "nightly", "beta", ou une URL vers un zip personnalisé. Consultez le schéma pour la liste complète.

Raccourcis vs étapes

Les raccourcis (login, plugins, siteOptions, constants) sont développés et ajoutés au début de steps dans un ordre non spécifié. Utilisez des étapes explicites quand l'ordre d'exécution est important.

Références de ressources

Les ressources indiquent à Playground où trouver les fichiers. Utilisées par installPlugin, installTheme, writeFile, writeFiles, importWxr, etc.

git:directory — Installation depuis GitHub

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}

• Quand vous utilisez un nom de branche ou de tag pour ref, vous devez définir refType ("branch" | "tag" | "commit" | "refname"). Sans cela, seul "HEAD" se résout de manière fiable.
• path sélectionne un sous-répertoire (par défaut la racine du repo).

literal:directory — Arborescences de fichiers en ligne

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}

• files utilise des objets imbriqués pour les sous-répertoires — les clés sont des noms de fichiers ou de répertoires, les valeurs sont des chaînes simples (contenu du fichier) ou des objets (sous-répertoires). N'utilisez jamais de références de ressources comme valeurs.
• N'utilisez PAS de séparateurs de chemin dans les clés (ex. "includes/helper.php" est faux — utilisez un objet "includes": { "helper.php": "..." } imbriqué).

Référence des étapes

Chaque étape nécessite "step": "<name>". Toute étape peut optionnellement inclure "progress": { "weight": 1, "caption": "Installing..." } pour les retours visuels.

Installation de plugins et thèmes

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}

{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}

• Utilisez pluginData / themeData — PAS les anciens pluginZipFile / themeZipFile.
• pluginData / themeData acceptent toute FileReference ou DirectoryReference — une URL zip, un slug wordpress.org/plugins, un git:directory, ou un literal:directory (pas besoin d'enveloppe zip).
• options.activate contrôle l'activation. Pas besoin d'une étape activatePlugin/activateTheme séparée quand vous utilisez installPlugin/installTheme.
• ifAlreadyInstalled : "overwrite" | "skip" | "error"

Activation (autonome)

Nécessaire uniquement pour les plugins/thèmes déjà sur disque (ex. après writeFile/writeFiles) :

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

Opérations sur fichiers

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data accepte une chaîne simple (comme montré ci-dessus) ou une référence de ressource (ex. { "resource": "url", "url": "https://..." }).

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFiles nécessite une DirectoryReference (literal:directory ou git:directory) comme filesTree — pas un objet simple.

Autres opérations sur fichiers : mkdir, cp, mv, rm, rmdir, unzip.

Exécution de code

runPHP :

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

PIÈGES : Vous devez require '/wordpress/wp-load.php'; pour utiliser n'importe quelles fonctions WordPress.

wp-cli :

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

Le nom de l'étape est wp-cli (avec tiret), PAS cli ou wpcli.

runSql :

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

Configuration du site

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }

{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }

{ "step": "setSiteLanguage", "language": "en_US" }

{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

Autres étapes

Modèles courants

Mu-plugin en ligne (code personnalisé rapide)

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins se chargent automatiquement — pas d'activation nécessaire, pas de require wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

Plugin en ligne avec plusieurs fichiers

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

Puis l'activez avec une étape séparée :

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

Plugin depuis une branche GitHub

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

Erreurs courantes

Référence complète

Cette compétence couvre les étapes et modèles les plus courants. Pour l'API complète, consultez :

• Documentation Blueprint : https://wordpress.github.io/wordpress-playground/blueprints
• Schéma JSON : https://playground.wordpress.net/blueprint-schema.json

Étapes supplémentaires non couvertes ci-dessus : runPHPWithOptions (exécuter PHP avec des paramètres ini personnalisés), runWpInstallationWizard, et types de ressources vfs et bundled (pour les scénarios d'intégration avancés).

Paquets Blueprint

Les paquets sont des packages autonomes qui incluent un blueprint.json ainsi que toutes les ressources qu'il référence (plugins, thèmes, fichiers WXR, etc.). Au lieu d'héberger les ressources en externe, empaquetez-les aux côtés du blueprint.

Structure du paquet

my-bundle/
├── blueprint.json          ← doit être à la racine
├── my-plugin.zip           ← répertoire plugin compressé
├── theme.zip
└── content/
    └── sample-content.wxr

Les plugins et thèmes doivent être compressés avant empaquetage — installPlugin attend un zip, pas un répertoire brut. Pour créer le zip à partir d'un répertoire de plugin :

cd my-bundle
zip -r my-plugin.zip my-plugin/

Référencement des ressources empaquetées

Utilisez le type de ressource bundled pour référencer les fichiers du paquet :

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "bundled",
    "path": "/my-plugin.zip"
  },
  "options": { "activate": true }
}

{
  "step": "importWxr",
  "file": {
    "resource": "bundled",
    "path": "/content/sample-content.wxr"
  }
}

Création d'un paquet étape par étape

1. Créez le répertoire du paquet et ajoutez blueprint.json à sa racine.
2. Écrivez vos fichiers source de plugin/thème dans un sous-répertoire (ex. my-plugin/my-plugin.php).
3. Compressez le répertoire du plugin : zip -r my-plugin.zip my-plugin/
4. Référencez-le dans blueprint.json en utilisant { "resource": "bundled", "path": "/my-plugin.zip" }.

Exemple complet — un paquet qui installe un plugin personnalisé :

dashboard-widget-bundle/
├── blueprint.json
├── dashboard-widget.zip        ← zip de dashboard-widget/
└── dashboard-widget/           ← source du plugin (conservée pour l'édition)
    └── dashboard-widget.php

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "bundled", "path": "/dashboard-widget.zip" },
      "options": { "activate": true }
    }
  ]
}

Formats de distribution

PIÈGE : Les paquets de répertoire local nécessitent toujours --blueprint-may-read-adjacent-files pour que le CLI lise les ressources empaquetées. Sans cela, toute référence "resource": "bundled" échouera avec une erreur "File not found". Les paquets ZIP n'ont pas besoin de cet indicateur — tous les fichiers sont autonomes dans l'archive.

Test des Blueprints

Blueprints en ligne (test rapide, pas de paquets)

Minifiez le JSON Blueprint (pas d'espaces supplémentaires), ajoutez https://playground.wordpress.net/# au début, et ouvrez l'URL dans un navigateur :

https://playground.wordpress.net/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}

Les très grands Blueprints peuvent dépasser les limites de longueur d'URL du navigateur ; utilisez le CLI à la place.

Test local avec CLI

Serveur interactif (continue à tourner, s'ouvre dans un navigateur) :

# Paquet répertoire — nécessite --blueprint-may-read-adjacent-files
npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

# Paquet ZIP — autonome, pas d'indicateurs supplémentaires nécessaires
npx @wp-playground/cli server --blueprint=./bundle.zip

Validation sans affichage (exécute le blueprint et quitte) :

npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

Test avec la compétence wordpress-playground-server

Utilisez la compétence wordpress-playground-server pour démarrer une instance Playground locale avec --blueprint /path/to/blueprint.json, puis vérifiez l'état attendu avec MCP Playwright. Pour les paquets répertoire, passez --blueprint-may-read-adjacent-files comme argument supplémentaire.