Skip to content

Rename the project to WordPress Playground #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 13, 2022
Merged

Rename the project to WordPress Playground #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# WordPress Sandbox
# WordPress Playground

[Live demo](https://wasm.wordpress.net/wordpress.html) | [Documentation and API Reference](https://wordpresswasm.readthedocs.io/en/latest/)

[WordPress Sandbox](https://github.com/WordPress/wordpress-sandbox) is an in-browser WordPress that runs without a PHP server thanks to the magic of WebAssembly.
[WordPress Playground](https://github.com/WordPress/wordpress-playground) is an in-browser WordPress that runs without a PHP server thanks to the magic of WebAssembly.

![](https://raw.githubusercontent.com/wordpress/wordpress-sandbox/trunk/demo.png)
![](https://raw.githubusercontent.com/wordpress/wordpress-playground/trunk/demo.png)

## Why is WordPress Sandbox useful?
## Why is WordPress Playground useful?

WordPress Sandbox is a foundation you can build on top of. Here's a few ideas what you could build:
WordPress Playground is a foundation you can build on top of. Here's a few ideas what you could build:

- Runnable code snippets in your documentation or course
- Plugin and theme demos in a private WordPress instance where the user is already logged in as an admin
Expand All @@ -20,23 +20,23 @@ See

## Getting started

WordPress Sandbox has a [live demo](https://developer.wordpress.org/sandbox/demo/) available.
WordPress Playground has a [live demo](https://developer.wordpress.org/playground/demo/) available.

You can embed WordPress Sandbox in your project via an `<iframe>` – find out how in the [documentation](https://wordpresswasm.readthedocs.io/en/latest/).
You can embed WordPress Playground in your project via an `<iframe>` – find out how in the [documentation](https://wordpresswasm.readthedocs.io/en/latest/).

You also can run WordPress Sandbox locally as follows:
You also can run WordPress Playground locally as follows:

```bash
git clone https://github.com/WordPress/wordpress-sandbox
cd wordpress-sandbox
git clone https://github.com/WordPress/wordpress-playground
cd wordpress-playground
npm install
npm run dev
```

A browser should open and take you to your very own client-side WordPress at [http://127.0.0.1:8777/wordpress.html](http://127.0.0.1:8777/wordpress.html)!

From here, the [documentation](https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs) will help you learn how WordPress Sandbox works and how to use it to build amazing things!
From here, the [documentation](https://github.com/WordPress/wordpress-playground/tree/trunk/docs) will help you learn how WordPress Playground works and how to use it to build amazing things!

## Contributing

WordPress Sandbox is an ambitious project in its early days. If the feature you need is missing, you are more than welcome to start a discussion, open an issue, and even propose a Pull Request to implement it.
WordPress Playground is an ambitious project in its early days. If the feature you need is missing, you are more than welcome to start a discussion, open an issue, and even propose a Pull Request to implement it.
58 changes: 29 additions & 29 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
<!-- this file is autogenerated, do not modify it directly -->
# WordPress Sandbox
# WordPress Playground

WordPress Sandbox is a WordPress running in the browser without a PHP server.
WordPress Playground is a WordPress running in the browser without a PHP server.

Try out the [WordPress Sandbox demo](https://developer.wordpress.org/sandbox/demo/) to:
Try out the [WordPress Playground demo](https://developer.wordpress.org/playground/demo/) to:

* Test-drive plugins and themes
* Experiment with an anonymous WordPress website
* Embed a real WordPress site in your tutorial or course

## Getting started

You can bring WordPress Sandbox to your project in a few different ways:
You can bring WordPress Playground to your project in a few different ways:

* Embed WordPress Sandbox on your website via an iframe
* Embed WordPress Playground on your website via an iframe
* Customize the preinstalled WordPress
* Extend and contribute to WordPress Sandbox
* Extend and contribute to WordPress Playground

### Embed WordPress Sandbox on your website via an iframe
### Embed WordPress Playground on your website via an iframe

<!-- include /docs/using-wordpress-in-the-browser.md#Embedding WordPress Sandbox on other websites -->
<!-- include /docs/using-wordpress-in-the-browser.md#Embedding WordPress Playground on other websites -->

The public WordPress Sandbox available at [https://wasm.wordpress.net/wordpress.html](https://wasm.wordpress.net/wordpress.html) may be embedded on other websites via the `<iframe>` HTML tag as follows:
The public WordPress Playground available at [https://wasm.wordpress.net/wordpress.html](https://wasm.wordpress.net/wordpress.html) may be embedded on other websites via the `<iframe>` HTML tag as follows:

```html
<iframe
Expand All @@ -41,7 +41,7 @@ Here are all the supported configuration options:
* `theme=disco` – Installs the specified theme. Use the theme name from the themes directory URL, e.g. for a URL like `https://wordpress.org/themes/disco/`, the theme name would be `disco`. Installing a theme automatically logs the user in as an admin.
* `rpc=1` – Enables the experimental JavaScript API.

For example, the following code embeds a Sandbox with a preinstalled Gutenberg plugin, and opens the post editor:
For example, the following code embeds a Playground with a preinstalled Gutenberg plugin, and opens the post editor:

```html
<iframe
Expand All @@ -50,60 +50,60 @@ For example, the following code embeds a Sandbox with a preinstalled Gutenberg p
></iframe>
```

<!-- /include /docs/using-wordpress-in-the-browser.md#Embedding WordPress Sandbox on other websites -->
<!-- /include /docs/using-wordpress-in-the-browser.md#Embedding WordPress Playground on other websites -->

The embedded iframe can be controlled via an experimental JavaScript API. Learn more at the [Running WordPress in the browser documentation page](./using-wordpress-in-the-browser.md#).

### Customize the preinstalled WordPress

You can customize the built-in WordPress installation to get more freedom than the embedded Sandbox has to offer. This is the right path to choose if you want to:
You can customize the built-in WordPress installation to get more freedom than the embedded Playground has to offer. This is the right path to choose if you want to:

* Use a specific WordPress version
* Directly control the Sandbox iframe contents
* Directly control the Playground iframe contents
* Preload a plugin or theme that's not in the directory
* Load a preconfigured WordPress instead of configuring it after the page load

To get started, create a local development build of WordPress Sandbox:
To get started, create a local development build of WordPress Playground:

```js
git clone https://github.com/WordPress/wordpress-sandbox
cd wordpress-sandbox
git clone https://github.com/WordPress/wordpress-playground
cd wordpress-playground
npm install
npm run dev
```

A browser should open and take you to your very own WordPress Sandbox at `http://127.0.0.1:8777/wordpress.html`!
A browser should open and take you to your very own WordPress Playground at `http://127.0.0.1:8777/wordpress.html`!

You can now customize the WordPress installation by adjusting [the build script](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/wordpress-sandbox/wordpress) and rebuilding WordPress with `npm run build:wp`. Learn more at the [WordPress in the browser documentation page](./using-wordpress-in-the-browser.md#).
You can now customize the WordPress installation by adjusting [the build script](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/wordpress-playground/wordpress) and rebuilding WordPress with `npm run build:wp`. Learn more at the [WordPress in the browser documentation page](./using-wordpress-in-the-browser.md#).

### Extend and contribute to WordPress Sandbox
### Extend and contribute to WordPress Playground

Custom apps may require features that are not available in WordPress Sandbox yet. That's an excellent opportunity to contribute to this project.
Custom apps may require features that are not available in WordPress Playground yet. That's an excellent opportunity to contribute to this project.

**You don't need to know WebAssembly to extend WordPress Sandbox.** WebAssembly knowledge is useful for altering the PHP interpreter, e.g. adding a custom PHP extension, but most of the meaningful work happens in the JavaScript in PHP land.
**You don't need to know WebAssembly to extend WordPress Playground.** WebAssembly knowledge is useful for altering the PHP interpreter, e.g. adding a custom PHP extension, but most of the meaningful work happens in the JavaScript in PHP land.

You could build an interactive code editor using just PHP and JavaScript. Or you could build a staging website environment where users can try out new plugins before adding them to the live website. In fact, almost every [open issue on GitHub](https://github.com/WordPress/wordpress-sandbox/issues) can be addressed with JavaScript and PHP.
You could build an interactive code editor using just PHP and JavaScript. Or you could build a staging website environment where users can try out new plugins before adding them to the live website. In fact, almost every [open issue on GitHub](https://github.com/WordPress/wordpress-playground/issues) can be addressed with JavaScript and PHP.

To get started, create a local development build of WordPress Sandbox:
To get started, create a local development build of WordPress Playground:

```js
git clone https://github.com/WordPress/wordpress-sandbox
cd wordpress-sandbox
git clone https://github.com/WordPress/wordpress-playground
cd wordpress-playground
npm install
npm run dev
```

A browser should open and take you to your very own WordPress Sandbox at `http://127.0.0.1:8777/wordpress.html`!
A browser should open and take you to your very own WordPress Playground at `http://127.0.0.1:8777/wordpress.html`!

From here, the [API Reference](./api) and the architecture overview below will help you find your way.

## Architecture overview

### Running WordPress in the browser

The `wordpress-sandbox` package uses [php-wasm](https://github.com/WordPress/wordpress-sandbox/blob/trunk/docs/using-php-in-javascript.md) and [php-wasm-browser](https://github.com/WordPress/wordpress-sandbox/blob/trunk/docs/using-php-in-the-browser.md) to run WordPress fully in the browser and without a PHP server. It consists of:
The `wordpress-playground` package uses [php-wasm](https://github.com/WordPress/wordpress-playground/blob/trunk/docs/using-php-in-javascript.md) and [php-wasm-browser](https://github.com/WordPress/wordpress-playground/blob/trunk/docs/using-php-in-the-browser.md) to run WordPress fully in the browser and without a PHP server. It consists of:

- Embeddable sandbox web page
- Embeddable playground web page
- WordPress web bundler
- WordPress-specific setup for the Worker Thread and the Service Worker
- WordPress-specific automations for tasks like signing in or installing plugins
Expand All @@ -115,7 +115,7 @@ See [running WordPress in the browser](./using-wordpress-in-the-browser.md) to l

The `php-wasm-browser` package provides tools to run `php-wasm` in the browser:

![The boot sequence](https://raw.githubusercontent.com/wordpress/wordpress-sandbox/trunk/docs/boot-sequence.png)
![The boot sequence](https://raw.githubusercontent.com/wordpress/wordpress-playground/trunk/docs/boot-sequence.png)

It consists of:

Expand Down
10 changes: 5 additions & 5 deletions docs/using-php-in-javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ console.log(php.run(`<?php echo "Hello from PHP!";`).stdout);

## PHP to WebAssembly build pipeline

The pipeline lives in [`wasm/Dockerfile`](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/php-wasm/wasm/Dockerfile). It was originally forked from [seanmorris/php-wasm](https://github.com/seanmorris/php-wasm)
The pipeline lives in [`wasm/Dockerfile`](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/php-wasm/wasm/Dockerfile). It was originally forked from [seanmorris/php-wasm](https://github.com/seanmorris/php-wasm)

In broad strokes, that `Dockerfile`:

Expand All @@ -33,29 +33,29 @@ In broad strokes, that `Dockerfile`:
- Outputs a `php.wasm` file and one or more JavaScript loaders, depending on the configuration.
- Transforms the Emscripten's default `php.js` output into an ESM module with additional features.

To find out more about each step, refer directly to the [Dockerfile](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/php-wasm/wasm/Dockerfile).
To find out more about each step, refer directly to the [Dockerfile](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/php-wasm/wasm/Dockerfile).

### Building

To build, run `npm run build:php:web` in the repository root. You'll find the output files in `packages/php-wasm/build-wasm`.

### PHP extensions

PHP is built with several extensions listed in the [`Dockerfile`](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/php-wasm/wasm/Dockerfile).
PHP is built with several extensions listed in the [`Dockerfile`](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/php-wasm/wasm/Dockerfile).

Some extensions, like `zip`, can be turned on or off during the build. Others, like `sqlite3`, are hardcoded.

If you need to turn off one of the hardcoded extensions, feel free to open an issue in this repo. Better yet, this project needs contributors. You are more than welcome to open a PR and author the change you need.

### C API exposed to JavaScript

The C API exposed to JavaScript lives in the [`wasm/build-assets/php_wasm.c`](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/php-wasm/wasm/build-assets/php_wasm.c) file. The most important functions are:
The C API exposed to JavaScript lives in the [`wasm/build-assets/php_wasm.c`](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/php-wasm/wasm/build-assets/php_wasm.c) file. The most important functions are:

- `void phpwasm_init()` – It creates a new PHP context and must be called before running any PHP code.
- `int phpwasm_run(char *code)` – Runs a PHP script and writes the output to /tmp/stdout and /tmp/stderr. Returns the exit code.
- `void phpwasm_refresh()` – Destroy the current PHP context and starts a new one. Call it after running one PHP script and before running another.

Refer to the inline documentation in [`php_wasm.c`](https://github.com/WordPress/wordpress-sandbox/blob/trunk/packages/php-wasm/wasm/build-assets/php_wasm.c) to learn more.
Refer to the inline documentation in [`php_wasm.c`](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/php-wasm/wasm/build-assets/php_wasm.c) to learn more.

### Build configuration

Expand Down
8 changes: 4 additions & 4 deletions docs/using-php-in-the-browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Keep this point in mind as you read through the rest of the docs. At this point

Here's what a boot sequence for a minimal app looks like:

![The boot sequence](https://raw.githubusercontent.com/wordpress/wordpress-sandbox/trunk/docs/boot-sequence.png)
![The boot sequence](https://raw.githubusercontent.com/wordpress/wordpress-playground/trunk/docs/boot-sequence.png)

The main app initiates the Iframe, the Service Worker, and the Worker Thread. Note how the main app doesn't use the PHP stack directly – it's all handled in the Worker Thread.

Expand Down Expand Up @@ -99,7 +99,7 @@ Keep reading to learn how all these pieces fit together.

Here's what happens whenever the iframe issues a same-domain request:

![The data flow](https://raw.githubusercontent.com/wordpress/wordpress-sandbox/trunk/docs/data-flow.png)
![The data flow](https://raw.githubusercontent.com/wordpress/wordpress-playground/trunk/docs/data-flow.png)

A step-by-step breakown:

Expand Down Expand Up @@ -248,7 +248,7 @@ Worker threads can use any multiprocessing technique like an iframe, WebWorker,

##### `webworker`

Spins a new `Worker` instance with the given Worker Thread script. This is the classic solution for multiprocessing in the browser and it almost became the only, non-configurable backend. The `iframe` backend only exists due to a Google Chrome bug that makes web workers prone to crashes when they're running WebAssembly. See [WASM file crashes Google Chrome](https://github.com/WordPress/wordpress-sandbox/issues/1) to learn more details.
Spins a new `Worker` instance with the given Worker Thread script. This is the classic solution for multiprocessing in the browser and it almost became the only, non-configurable backend. The `iframe` backend only exists due to a Google Chrome bug that makes web workers prone to crashes when they're running WebAssembly. See [WASM file crashes Google Chrome](https://github.com/WordPress/wordpress-playground/issues/1) to learn more details.

Example usage:

Expand Down Expand Up @@ -407,7 +407,7 @@ Scopes keep your app working when you open it in two different different browser

The Service Worker passes the intercepted HTTP requests to the PHPServer for rendering. Technically, it sends a message through a [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) which then gets delivered to every browser tab where the application is open. This is undesirable, slow, and leads to unexpected behaviors.

Unfortunately, the Service Worker cannot directly communicate with the relevant Worker Thread – see [PR #31](https://github.com/WordPress/wordpress-sandbox/pull/31) and [issue #9](https://github.com/WordPress/wordpress-sandbox/issues/9) for more details.
Unfortunately, the Service Worker cannot directly communicate with the relevant Worker Thread – see [PR #31](https://github.com/WordPress/wordpress-playground/pull/31) and [issue #9](https://github.com/WordPress/wordpress-playground/issues/9) for more details.

Scopes enable each browser tab to:

Expand Down
Loading