API Consistency
https://github.com/WordPress/wordpress-playground/pull/215
JSON API and Function API
Blueprints are defined in JSON format, but the underlying implementation uses JavaScript functions to execute the steps. While JSON is the most convenient way of interacting with Blueprints, you can also use the underlying functions directly.
JSON is merely a wrapper around the functions. Whether you use the JSON steps or the exported functions, you'll have to provide the same parameters (except for the step name):
activatePlugin
Activates a WordPress plugin (if it's installed).
Parameters
- pluginName (string) – Optional. Plugin name to display in the progress bar.
- pluginPath (string) – Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php).
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "activatePlugin",
"pluginName": "Gutenberg",
"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
}
]
}
import { activatePlugin } from '@wp-playground/blueprints';
activatePlugin(
playground,
{
"step": "activatePlugin",
"pluginName": "Gutenberg",
"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
},
progress
)
activateTheme
Activates a WordPress theme (if it's installed).
Parameters
- themeFolderName (string) – The name of the theme folder inside wp-content/themes/
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "activateTheme",
"themeFolderName": "storefront"
}
]
}
import { activateTheme } from '@wp-playground/blueprints';
activateTheme(
playground,
{
"step": "activateTheme",
"themeFolderName": "storefront"
},
progress
)
cp
Copies a file from one path to another.
Parameters
- fromPath (string) – Source path
- toPath (string) – Target path
Example
- Blueprint API
- Function API
{
"landingPage": "/index2.php",
"steps": [
{
"step": "cp",
"fromPath": "/wordpress/index.php",
"toPath": "/wordpress/index2.php"
}
]
}
import { cp } from '@wp-playground/blueprints';
cp(
playground,
{
"step": "cp",
"fromPath": "/wordpress/index.php",
"toPath": "/wordpress/index2.php"
},
progress
)
defineSiteUrl
Sets WP_HOME
and WP_SITEURL
constants for the WordPress installation.
Using this step on playground.wordpress.net is moot.
It is useful when building a custom Playground-based tool, like wp-now
,
or deploying Playground on a custom domain.
Parameters
- siteUrl (string) – The URL
defineWpConfigConsts
Defines constants in a wp-config.php
file.
This step can be called multiple times, and the constants will be merged.
Parameters
- consts (Record) – The constants to define
- method – The method of defining the constants in wp-config.php. Possible values are: - rewrite-wp-config: Default. Rewrites the wp-config.php file to explicitly call define() with the requested name and value. This method alters the file on the disk, but it doesn't conflict with existing define() calls in wp-config.php. - define-before-run: Defines the constant before running the requested script. It doesn't alter any files on the disk, but constants defined this way may conflict with existing define() calls in wp-config.php.
- virtualize (boolean)
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
}
]
}
import { defineWpConfigConsts } from '@wp-playground/blueprints';
defineWpConfigConsts(
playground,
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
},
progress
)
enableMultisite
Defines the Multisite constants in a wp-config.php
file.
This step can be called multiple times, and the constants will be merged.
Parameters
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "enableMultisite"
}
]
}
import { enableMultisite } from '@wp-playground/blueprints';
enableMultisite(
playground,
{
"step": "enableMultisite"
},
progress
)
importWordPressFiles
Imports top-level WordPress files from a given zip file into
the documentRoot
. For example, if a zip file contains the
wp-content
and wp-includes
directories, they will replace
the corresponding directories in Playground's documentRoot
.
Any files that Playground recognizes as "excluded from the export" will carry over from the existing document root into the imported directories. For example, the sqlite-database-integration plugin.
Parameters
- pathInZip (string) – The path inside the zip file where the WordPress files are.
- wordPressFilesZip (ResourceType) – The zip file containing the top-level WordPress files and directories.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "importWordPressFiles",
"wordPressFilesZip": {
"resource": "url",
"url": "https://mysite.com/import.zip"
}
}
]
}
import { importWordPressFiles } from '@wp-playground/blueprints';
importWordPressFiles(
playground,
{
"step": "importWordPressFiles",
"wordPressFilesZip": await fetchMyFile()
},
progress
)
importWxr
Imports a WXR file into WordPress.
Parameters
- file (ResourceType) – The file to import
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "importWxr",
"file": {
"resource": "url",
"url": "https://your-site.com/starter-content.wxr"
}
}
]
}
import { importWxr } from '@wp-playground/blueprints';
importWxr(
playground,
{
"step": "importWxr",
"file": await fetchMyFile()
},
progress
)
installPlugin
Installs a WordPress plugin in the Playground.
Parameters
- ifAlreadyInstalled – What to do if the asset already exists.
- options (InstallPluginOptions) – Optional installation options.
- pluginZipFile (ResourceType) – The plugin zip file to install.
Example
- Blueprint API
- Function API
{
"landingPage": "/wp-admin/plugins.php",
"steps": [
{
"step": "login"
},
{
"step": "installPlugin",
"pluginZipFile": {
"resource": "wordpress.org/plugins",
"slug": "gutenberg"
},
"options": {
"activate": true
}
}
]
}
import { installPlugin } from '@wp-playground/blueprints';
installPlugin(
playground,
{
"step": "installPlugin",
"pluginZipFile": await fetchMyFile(),
"options": {
"activate": true
}
},
progress
)
installTheme
Installs a WordPress theme in the Playground.
Parameters
- ifAlreadyInstalled – What to do if the asset already exists.
- options – Optional installation options.
- themeZipFile (ResourceType) – The theme zip file to install.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "login"
},
{
"step": "installTheme",
"themeZipFile": {
"resource": "wordpress.org/themes",
"slug": "pendant"
},
"options": {
"activate": true
}
}
]
}
import { installTheme } from '@wp-playground/blueprints';
installTheme(
playground,
{
"step": "installTheme",
"themeZipFile": await fetchMyFile(),
"options": {
"activate": true
}
},
progress
)
login
Logs in to Playground.
Under the hood, this function submits the wp-login.php
form
just like a user would.
Parameters
- password (string) – The password to log in with. Defaults to 'password'.
- username (string) – The user to log in as. Defaults to 'admin'.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "login",
"username": "admin",
"password": "password"
}
]
}
import { login } from '@wp-playground/blueprints';
login(
playground,
{
"step": "login",
"username": "admin",
"password": "password"
},
progress
)
mkdir
Creates a directory at the specified path.
Parameters
- path (string) – The path of the directory you want to create
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "mkdir",
"path": "/wordpress/my-new-folder"
}
]
}
import { mkdir } from '@wp-playground/blueprints';
mkdir(
playground,
{
"step": "mkdir",
"path": "/wordpress/my-new-folder"
},
progress
)
mv
Moves a file or directory from one path to another.
Parameters
- fromPath (string) – Source path
- toPath (string) – Target path
Example
- Blueprint API
- Function API
{
"landingPage": "/index2.php",
"steps": [
{
"step": "mv",
"fromPath": "/wordpress/index.php",
"toPath": "/wordpress/index2.php"
}
]
}
import { mv } from '@wp-playground/blueprints';
mv(
playground,
{
"step": "mv",
"fromPath": "/wordpress/index.php",
"toPath": "/wordpress/index2.php"
},
progress
)
rm
Removes a file at the specified path.
Parameters
- path (string) – The path to remove
Example
- Blueprint API
- Function API
{
"landingPage": "/index.php",
"steps": [
{
"step": "rm",
"path": "/wordpress/index.php"
}
]
}
import { rm } from '@wp-playground/blueprints';
rm(
playground,
{
"step": "rm",
"path": "/wordpress/index.php"
},
progress
)
rmdir
Removes a directory at the specified path.
Parameters
- path (string) – The path to remove
Example
- Blueprint API
- Function API
{
"landingPage": "/wp-admin/",
"steps": [
{
"step": "rmdir",
"path": "/wordpress/wp-admin"
}
]
}
import { rmdir } from '@wp-playground/blueprints';
rmdir(
playground,
{
"step": "rmdir",
"path": "/wordpress/wp-admin"
},
progress
)
runPHP
Runs PHP code.
When running WordPress functions, the code
key must first load wp-load.php
and start with "<?php require_once 'wordpress/wp-load.php'; "
.
Parameters
- code (string) – The PHP code to run.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "runPHP",
"code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
}
]
}
import { runPHP } from '@wp-playground/blueprints';
runPHP(
playground,
{
"step": "runPHP",
"code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
},
progress
)
runPHPWithOptions
Runs PHP code.
When running WordPress functions, the code
key must first load wp-load.php
and start with "<?php require_once 'wordpress/wp-load.php'; "
.
Parameters
- options (PHPRunOptions) – Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/))
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "runPHP",
"options": {
"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
"headers": {
"Content-type": "text/plain"
}
}
}
]
}
import { runPHPWithOptions } from '@wp-playground/blueprints';
runPHPWithOptions(
playground,
{
"step": "runPHP",
"options": {
"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
"headers": {
"Content-type": "text/plain"
}
}
},
progress
)
runSql
Run one or more SQL queries.
This step will treat each non-empty line in the input SQL as a query and
try to execute it using $wpdb
. Queries spanning multiple lines are not
yet supported.
Parameters
- sql (ResourceType) – The SQL to run. Each non-empty line must contain a valid SQL query.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "runSql",
"sql": {
"resource": "literal",
"name": "schema.sql",
"contents": "DELETE FROM wp_posts"
}
}
]
}
import { runSql } from '@wp-playground/blueprints';
runSql(
playground,
{
"step": "runSql",
"sql": await fetchMyFile()
},
progress
)
setSiteOptions
Sets site options. This is equivalent to calling update_option
for each
option in the options
object.
Parameters
- options (Record) – The options to set on the site.
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "setSiteOptions",
"options": {
"blogname": "My Blog",
"blogdescription": "A great blog"
}
}
]
}
import { setSiteOptions } from '@wp-playground/blueprints';
setSiteOptions(
playground,
{
"step": "setSiteOptions",
"options": {
"blogname": "My Blog",
"blogdescription": "A great blog"
}
},
progress
)
unzip
Unzip a zip file.
Parameters
- extractToPath (string) – The path to extract the zip file to
- zipFile (ResourceType) – The zip file to extract
- zipPath (string) – The path of the zip file to extract
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "unzip",
"zipFile": {
"resource": "vfs",
"path": "/wordpress/data.zip"
},
"extractToPath": "/wordpress"
}
]
}
import { unzip } from '@wp-playground/blueprints';
unzip(
playground,
{
"step": "unzip",
"zipFile": await fetchMyFile(),
"extractToPath": "/wordpress"
},
progress
)
updateUserMeta
Updates user meta. This is equivalent to calling update_user_meta
for each
meta value in the meta
object.
Parameters
- meta (Record) – An object of user meta values to set, e.g. { "first_name": "John" }
- userId (number) – User ID
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "updateUserMeta",
"meta": {
"first_name": "John",
"last_name": "Doe"
},
"userId": 1
}
]
}
import { updateUserMeta } from '@wp-playground/blueprints';
updateUserMeta(
playground,
{
"step": "updateUserMeta",
"meta": {
"first_name": "John",
"last_name": "Doe"
},
"userId": 1
},
progress
)
wp-cli
Runs PHP code using WP-CLI.
Parameters
- command – The WP CLI command to run.
- wpCliPath (string) – wp-cli.phar path
Example
- Blueprint API
- Function API
{
"steps": [
{
"step": "wp-cli",
"command": "wp post create --post_title='Test post' --post_excerpt='Some content'"
}
]
}
import { wpCLI } from '@wp-playground/blueprints';
wpCLI(
playground,
{
"step": "wp-cli",
"command": "wp post create --post_title='Test post' --post_excerpt='Some content'"
},
progress
)
writeFile
Writes data to a file at the specified path.
Parameters
- data – The data to write
- path (string) – The path of the file to write to
Example
- Blueprint API
- Function API
{
"landingPage": "/test.php",
"steps": [
{
"step": "writeFile",
"path": "/wordpress/test.php",
"data": "<?php echo 'Hello World!'; ?>"
}
]
}
import { writeFile } from '@wp-playground/blueprints';
writeFile(
playground,
{
"step": "writeFile",
"path": "/wordpress/test.php",
"data": "<?php echo 'Hello World!'; ?>"
},
progress
)
You can use Blueprints both with the web and the node.js version of WordPress Playground.
Differences between JSON and Function APIs
There are two main differences between the JSON and Function APIs:
- Blueprints handle the progress bar and error reporting for you. The function API requires you to handle these yourself.
- The function API requires importing the API client library while Blueprints may be just pasted into the URL fragment.