Skip to main content

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.

The following step-related topics are addressed on dedicated pages included in this section:

  • Resources References allow you use external files in Blueprints.

  • Some steps have a shorthand version. Check the Shorthands section for more information about them.

  • For each step listed below, you'll find both a "Blueprint API" and a "Function API". Refer to the API Consistency page for further details.

tip

The WordPress Playground Step Library tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!


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

{
"steps": [
{
"step": "activatePlugin",
"pluginName": "Gutenberg",
"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
}
]
}

activateTheme

Activates a WordPress theme (if it's installed).

Parameters

  • themeFolderName (string) – The name of the theme folder inside wp-content/themes/

Example

{
"steps": [
{
"step": "activateTheme",
"themeFolderName": "storefront"
}
]
}

cp

Copies a file from one path to another.

Parameters

  • fromPath (string) – Source path
  • toPath (string) – Target path

Example

{
"landingPage": "/index2.php",
"steps": [
{
"step": "cp",
"fromPath": "/wordpress/index.php",
"toPath": "/wordpress/index2.php"
}
]
}

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

{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true
}
}
]
}

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

    {
    "steps": [
    {
    "step": "enableMultisite"
    }
    ]
    }

    importThemeStarterContent

    Imports a theme Starter Content into WordPress.

    Parameters

    • themeSlug (string) – The name of the theme to import content from.

    Example

    {
    "steps": [
    {
    "step": "importThemeStarterContent"
    }
    ]
    }

    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

    {
    "steps": [
    {
    "step": "importWordPressFiles",
    "wordPressFilesZip": {
    "resource": "url",
    "url": "https://mysite.com/import.zip"
    }
    }
    ]
    }

    importWxr

    Imports a WXR file into WordPress.

    Parameters

    • file (ResourceType) – The file to import

    Example

    {
    "steps": [
    {
    "step": "importWxr",
    "file": {
    "resource": "url",
    "url": "https://your-site.com/starter-content.wxr"
    }
    }
    ]
    }

    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

    {
    "landingPage": "/wp-admin/plugins.php",
    "steps": [
    {
    "step": "login"
    },
    {
    "step": "installPlugin",
    "pluginZipFile": {
    "resource": "wordpress.org/plugins",
    "slug": "gutenberg"
    },
    "options": {
    "activate": true
    }
    }
    ]
    }

    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

    {
    "steps": [
    {
    "step": "login"
    },
    {
    "step": "installTheme",
    "themeZipFile": {
    "resource": "wordpress.org/themes",
    "slug": "pendant"
    },
    "options": {
    "activate": true,
    "importStarterContent": true
    }
    }
    ]
    }

    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

    {
    "steps": [
    {
    "step": "login",
    "username": "admin",
    "password": "password"
    }
    ]
    }

    mkdir

    Creates a directory at the specified path.

    Parameters

    • path (string) – The path of the directory you want to create

    Example

    {
    "steps": [
    {
    "step": "mkdir",
    "path": "/wordpress/my-new-folder"
    }
    ]
    }

    mv

    Moves a file or directory from one path to another.

    Parameters

    • fromPath (string) – Source path
    • toPath (string) – Target path

    Example

    {
    "landingPage": "/index2.php",
    "steps": [
    {
    "step": "mv",
    "fromPath": "/wordpress/index.php",
    "toPath": "/wordpress/index2.php"
    }
    ]
    }

    resetData

    Deletes WordPress posts and comments and sets the auto increment sequence for the posts and comments tables to 0.

    Parameters

      Example

      {
      "steps": [
      {
      "step": "resetData"
      }
      ]
      }

      rm

      Removes a file at the specified path.

      Parameters

      • path (string) – The path to remove

      Example

      {
      "landingPage": "/index.php",
      "steps": [
      {
      "step": "rm",
      "path": "/wordpress/index.php"
      }
      ]
      }

      rmdir

      Removes a directory at the specified path.

      Parameters

      • path (string) – The path to remove

      Example

      {
      "landingPage": "/wp-admin/",
      "steps": [
      {
      "step": "rmdir",
      "path": "/wordpress/wp-admin"
      }
      ]
      }

      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

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

      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

      {
      "steps": [
      {
      "step": "runPHP",
      "options": {
      "code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
      "headers": {
      "Content-type": "text/plain"
      }
      }
      }
      ]
      }

      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

      {
      "steps": [
      {
      "step": "runSql",
      "sql": {
      "resource": "literal",
      "name": "schema.sql",
      "contents": "DELETE FROM wp_posts"
      }
      }
      ]
      }

      setSiteLanguage

      Sets the site language and download translations.

      Parameters

      • language (string) – The language to set, e.g. 'en_US'

      Example

      {
      "steps": [
      {
      "step": "setSiteLanguage",
      "language": "en_US"
      }
      ]
      }

      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

      {
      "steps": [
      {
      "step": "setSiteOptions",
      "options": {
      "blogname": "My Blog",
      "blogdescription": "A great blog"
      }
      }
      ]
      }

      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

      {
      "steps": [
      {
      "step": "unzip",
      "zipFile": {
      "resource": "vfs",
      "path": "/wordpress/data.zip"
      },
      "extractToPath": "/wordpress"
      }
      ]
      }

      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

      {
      "steps": [
      {
      "step": "updateUserMeta",
      "meta": {
      "first_name": "John",
      "last_name": "Doe"
      },
      "userId": 1
      }
      ]
      }

      wp-cli

      Runs PHP code using WP-CLI.

      Parameters

      • command – The WP CLI command to run.
      • wpCliPath (string) – wp-cli.phar path

      Example

      {
      "step": "wp-cli",
      "command": "wp post create --post_title='Test post' --post_excerpt='Some
      content'"
      }

      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

      {
      "landingPage": "/test.php",
      "steps": [
      {
      "step": "writeFile",
      "path": "/wordpress/test.php",
      "data": "<?php echo 'Hello World!'; ?>"
      }
      ]
      }