Reviewing a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. or theme Pull Request has always carried a bit of friction. To actually test the change, someone had to pull the branch, spin up a local WordPress, and activate the code by hand. That is exactly why the WordPress Playground PR Preview GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ Action exists: it adds a “Preview in WordPress Playground” button straight to the PR. As a result, any reviewer opens the environment with the code already applied in the browser, without installing anything.

The action already existed in v2. However, version 3 underwent an important simplification: the manual “glue” that each project had to write for builds was replaced by ready-made, reusable workflows. In this post, therefore, I’ll cover what the action does, why it’s worth it, how to set it up in the two possible scenarios, practical examples, and the step-by-step path to migrate from v2.

What the WordPress Playground PR Preview action does

In short, it publishes a preview link on the Pull Request. That link points to a WordPress Playground instance, in other words, a full WordPress running through WebAssembly (WASM) in the browser of whoever clicks it. Playground boots clean, installs the plugin or theme from the PR branch, and automatically activates everything.

The result, then, is a disposable, isolated environment created on demand that mirrors the state of that branch exactly.

Why use it

• One-click testing: the reviewer needs no local setup and no WordPress installed.
• Works with forks: external contributions get a preview without exposing repository secrets.
• Plugin, theme, or both: you can create scenarios that combine several artifacts.
• Handles complex builds: projects that rely on Composer, npm, or Vite are supported too, through dedicated workflows.
• Real sandbox: the code runs in the user’s browser, isolated, without touching any server.

Scenario 1: no build step

This is the simplest path. Use it when the files committed to the repository run as-is, without compilation, for example, a plain PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php plugin.

First, create .github/workflows/pr-preview.yml:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: WordPress/action-wp-playground-pr-preview@v3
        with:
          plugin-path: .
          github-token: ${{ secrets.GITHUB_TOKEN }}

For a theme, swap plugin-path: . for theme-path: .. Besides that, the permissions blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. is mandatory: the action needs pull-requests: write to write the link on the PR and contents: read to read the code.

Main inputs of the direct action

You provide one of plugin-path, theme-path, blueprint, or blueprint-url. The mode, in turn, decides whether the link goes into the PR description body or as a comment.

Scenario 2: with a build step

When the preview depends on compilation (npm run build, Composer, etc.), v3 uses two workflows that talk to each other. First, one builds the untrusted PR code with read-only permissions. Then, the other publishes the result from the default branch, with write permissions, without ever executing the PR code. The only point of contact between them is the generated ZIP file — and that is precisely what keeps the flow secure.

The build workflow lives in .github/workflows/pr-preview-build.yml:

name: PR Preview - Build
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  build:
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v3
    with:
      artifacts: my-plugin=build/my-plugin.zip
      node-version: '20'
      build-command: |
        npm ci
        npm run build:plugin-zip

The publish workflow, in turn, lives in .github/workflows/pr-preview-publish.yml:

name: PR Preview - Publish
on:
  workflow_run:
    workflows: ["PR Preview - Build"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    permissions:
      contents: write
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-publish.yml@v3
    with:
      kind: plugin

The artifacts field uses the name=path/to/file.zip format — one per line, if you have several. The kind in publish, meanwhile, tells whether the artifact is a plugin or a theme. Besides that, the reusable workflows take care of automatically creating a ci-artifacts prerelease to host the ZIPs publicly. After all, Playground needs to download the asset, so it can’t be in a draft release.

Build workflow inputs

Practical example: custom Blueprint

Sometimes you need more than “install and activate”. Say, a plugin from the PR running alongside WooCommerce and already logged in as admin. In that case, use a Blueprint. It’s a JSON recipe that describes the site’s initial state.

- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    blueprint: |
      {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "preferredVersions": { "php": "8.3", "wp": "6.6" },
        "steps": [
          { "step": "installPlugin",
            "pluginData": {
              "resource": "git:directory",
              "url": "https://github.com/${{ github.repository }}.git",
              "ref": "${{ github.event.pull_request.head.ref }}",
              "path": "/"
            },
            "options": { "activate": true } },
          { "step": "installPlugin",
            "pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" },
            "options": { "activate": true } },
          { "step": "login", "username": "admin" }
        ]
      }
    github-token: ${{ secrets.GITHUB_TOKEN }}

This Blueprint pins PHP 8.3 and WordPress 6.6, installs the code from the PR branch, adds WooCommerce from the official repository, and hands over an already-logged-in environment. For build scenarios, moreover, you can reference the generated ZIPs inside the Blueprint using the {{ARTIFACT_URL:<name>}} placeholder. That way, v3 resolves the public artifact URL for you.

Migrating from v2 to v3

In practice, the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. varies with the complexity of your setup.

Simple plugins and themes (no build): here, almost nothing changes. Switch the action reference from @v2 to @v3 and keep the same inputs.

# works the same in v2 and v3
- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    plugin-path: .
    github-token: ${{ secrets.GITHUB_TOKEN }}

Projects with a build: this is where the real gain is. On v2 you needed a build workflow, plus manual parsing of the artifact name, plus an expose-artifact-on-public-url helper, plus manual Blueprint generation, and still the manual release publishing. v3, by contrast, replaces all of that with the two reusable workflows (preview-build.yml and preview-publish.yml) shown above. The step-by-step, therefore, looks like this:

1. Create pr-preview-build.yml with the build workflow template.
2. Create pr-preview-publish.yml with the publish workflow template.
3. Define the artifacts in the artifacts field (name=path format).
4. Set kind: plugin or kind: theme in publish — or, alternatively, use blueprint with {{ARTIFACT_URL:<name>}} placeholders for setups with multiple ZIPs.

Inputs such as artifact-name, artifact-filename, artifact-source-run-id, pr-number, and commit-sha, which existed only for the manual glue, are no longer needed in most cases.

Finally, watch out for the mandatory release cleanup: the change that breaks the most in practice is that draft releases no longer work. After all, Playground can’t download assets from a draft release without authentication. Therefore, if you have ci-artifacts releases in draft, convert them to prerelease or delete them.

Common gotchas

• 404 error when opening the preview: the release is probably set as a draft instead of a prerelease. Fix it on the repository’s Releases tab.
• Plugin doesn’t show up as installed: the ZIP must be extracted to a folder named after the slug. Make sure your build does that. For example:
  bash mkdir -p stage/my-plugin && rsync -a ./ stage/my-plugin/ && (cd stage && zip -r ../my-plugin.zip my-plugin)
• Build failing when comparing against the base: if you use git diff against the base branch, set fetch-depth: 0 in the build workflow. After all, the default checkout brings only the latest commit.
• Permission error: the permissions block is missing at the workflow or job level.

Conclusion

If you already used v2 for builds, migrating is worth it: you delete dozens of lines of manual glue and get tested, community-maintained workflows in their place. On the other hand, if you don’t use PR preview in your plugin or theme repository yet, the no-build scenario solves it with a few lines of YAML — and noticeably improves the experience for whoever reviews code in your project.

The full documentation lives at wordpress.github.io/action-wp-playground-pr-preview. For the more specific cases, also check the detailed migration guide.

Every PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php version WordPress Playground supports ships as a WebAssembly binary. Across all builds and versions, those binaries totaled 888 MB. Two compiler flag changes reduced that to 766 MB, a 122 MB saving (13.7%) without removing a single feature.

What changed?

Playground compiles PHP to WebAssembly using Emscripten. The compiler flag MAIN_MODULE controls which symbols get exported for dynamic linking. Previously, Playground used MAIN_MODULE=1, which exports everything, including thousands of symbols that no extension ever calls.

Switching to MAIN_MODULE=2 tells Emscripten to export only the symbols extensions actually use, similar to tree-shaking in JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com bundlers. The compiler drops everything else.

The challenge: keeping extensions alive

Flipping a compiler flag sounds simple, but MAIN_MODULE=2 aggressively eliminates code that the main module considers “dead.” Playground loads extensions like Intl, Xdebug, Memcached, and Redis as dynamic .so modules, and those modules depend on specific symbols from the main PHP binary. Remove the wrong symbol, and the extension crashes on load.

PR #3244 first mapped the approach: scanning each compiled extension wasm-dis to extract which symbols it references. The build system then feeds those symbols back to the linker as explicit exports, keeping every extension working while eliminating thousands of unused ones.

Three extensions required direct fixes. Xdebug required a __c_longjmp WebAssembly tag injection. Memcached called recv and setsockopt through libmemcached internals, so the build added C shim wrappers. Intl alone needed over 5,000 export symbols, including libc++ functions.

Why two build types?

PHP is synchronous. Browsers are not. Playground solves this mismatch with two compilation strategies, and each one produces a separate set of binaries:

• Asyncify transforms compiled code at build time so it can pause and resume execution. This approach works in every browser but adds overhead to the binary. Learn more about Asyncify.
• JSPI (JavaScript Promise Integration) takes a different approach. It lets WebAssembly call async browser APIs directly, without transforming the compiled code. JSPI produces smaller binaries but currently requires V8-based browsers (Chrome, Edge). Learn more about JSPI.

Playground ships both variants for each PHP version, so the MAIN_MODULE=2 optimization is applied to both:

• PR #3332 targeted JSPI builds.
• PR #3335 completed the same change for Asyncify builds.

The numbers

Per-version .wasm sizes dropped consistently across all supported PHP versions:

The two PRs combined removed 554,793 lines of JavaScript glue code across all builds.

Why smaller binaries matter

Faster downloads and CI. 122 MB fewer bytes to transfer during repository clones, CI pipelines, and deployments. That adds up across all contributors and all automated runs.

Faster WebAssembly instantiation. Smaller .wasm files compile faster in the browser. Compilation cost scales roughly with binary size, so 16% smaller binaries translate directly to faster WordPress startup.

Lower memory usage. Fewer exported symbols produce a smaller function table. The runtime allocates less memory before PHP even starts.

Faster JavaScript parsing. 63% less JS glue code means the browser parses and evaluates significantly less JavaScript before handing control to PHP.

What this means for php-wasm packages

Version-specific packages like @php-wasm/web-8.4 and @php-wasm/node-8.4 ship lighter binaries. No APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. changes — this is purely a build optimization. Existing code that depends on these packages works unchanged.

What comes next

The next step is to benchmark the runtime impact by measuring instantiation time, time-to-first-PHP-response, and memory usage across builds. Those numbers will confirm how the smaller binaries translate to real-world performance gains.

Props to @mho22 for implementing both PRs and reviewing the post, @brandonpayton for reviewing, and @adamziel for the architectural direction. See the full details in PR #3332 and PR #3335.