Steps
The steps
property of a Blueprint is an array of steps to run. For example this Blueprint logs the user in as an admin:
{
"steps": [
{
"step": "login",
"username": "admin",
"password": "password"
}
]
}
Each step is an object that contains a step
property that specifies the type of step to run. The rest of the properties depend on the type of step. Learn and try each step type below.
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
)