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.

ActivatePluginStep

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
)

ActivateThemeStep

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
)

CpStep

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
)

DefineSiteUrlStep

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

DefineWpConfigConstsStep

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
)

EnableMultisiteStep

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
)

ImportWordPressFilesStep

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
)

ImportWxrStep

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
)

InstallPluginStep

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
)

InstallThemeStep

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
)

LoginStep

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
)

MkdirStep

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
)

MvStep

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
)

RmStep

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
)

RmdirStep

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
)

RunPHPStep

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
)

RunPHPWithOptionsStep

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
)

RunSqlStep

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
)

SetSiteOptionsStep

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
)

UnzipStep

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
)

UpdateUserMetaStep

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
)

WPCLIStep

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
)

WriteFileStep

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
)

Steps

ActivatePluginStep​

Parameters

Example

ActivateThemeStep​

Parameters

Example

CpStep​

Parameters

Example

DefineSiteUrlStep​

Parameters

DefineWpConfigConstsStep​

Parameters

Example

EnableMultisiteStep​

Parameters

Example

ImportWordPressFilesStep​

Parameters

Example

ImportWxrStep​

Parameters

Example

InstallPluginStep​

Parameters

Example

InstallThemeStep​

Parameters

Example

LoginStep​

Parameters

Example

MkdirStep​

Parameters

Example

MvStep​

Parameters

Example

RmStep​

Parameters

Example

RmdirStep​

Parameters

Example

RunPHPStep​

Parameters

Example

RunPHPWithOptionsStep​

Parameters

Example

RunSqlStep​

Parameters

Example

SetSiteOptionsStep​

Parameters

Example

UnzipStep​

Parameters

Example

UpdateUserMetaStep​

Parameters

Example

WPCLIStep​

Parameters

Example

WriteFileStep​

Parameters

Example

ActivatePluginStep

ActivateThemeStep

CpStep

DefineSiteUrlStep

DefineWpConfigConstsStep

EnableMultisiteStep

ImportWordPressFilesStep

ImportWxrStep

InstallPluginStep

InstallThemeStep

LoginStep

MkdirStep

MvStep

RmStep

RmdirStep

RunPHPStep

RunPHPWithOptionsStep

RunSqlStep

SetSiteOptionsStep

UnzipStep

UpdateUserMetaStep

WPCLIStep

WriteFileStep