diff --git a/README.md b/README.md index d253d4d78a..df9782d5fd 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 ` ``` - + 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. @@ -101,9 +101,9 @@ From here, the [API Reference](./api) and the architecture overview below will h ### 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 @@ -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: diff --git a/docs/using-php-in-javascript.md b/docs/using-php-in-javascript.md index abeeeef243..21da50cfca 100644 --- a/docs/using-php-in-javascript.md +++ b/docs/using-php-in-javascript.md @@ -21,7 +21,7 @@ console.log(php.run(` # WordPress in the browser -[API Reference](api/wordpress-sandbox.md) +[API Reference](api/wordpress-playground.md) -This 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. +This 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. -The `wordpress-sandbox` package consists of: +The `wordpress-playground` package 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 - A PHP proxy to download plugins and themes from the WordPress.org directory -## Embeddable sandbox web page +## Embeddable playground web page All parts of this repository come together in the `wordpress.html` page where WordPress is loaded and displayed. -### Embedding WordPress Sandbox on other websites +### 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 ` ``` -### Controlling the embedded WordPress Sandbox via JavaScript API +### Controlling the embedded WordPress Playground via JavaScript API **The JavaScript API is an early preview and will likely evolve in the future.** -The embedded Sandbox can be controlled from JavaScript via `window.postMessage` if you used the `rpc=1` option: +The embedded Playground can be controlled from JavaScript via `window.postMessage` if you used the `rpc=1` option: ```js -// Ask the Sandbox whether it has finished booting: -document.querySelector('#sandbox').contentWindow.postMessage({ +// Ask the Playground whether it has finished booting: +document.querySelector('#playground').contentWindow.postMessage({ type: 'is_booted', requestId: 1 }, '*'); -// Receive the messages from Sandbox: +// Receive the messages from Playground: function handleResponse(e) { if(e.data.type === 'response' && e.data.requestId === 1 && e.data.response === true) { - // Navigate to wp-admin if the Sandbox was booted: - document.querySelector('#sandbox').contentWindow.postMessage({ + // Navigate to wp-admin if the Playground was booted: + document.querySelector('#playground').contentWindow.postMessage({ type: 'go_to', path: '/wp-admin/index.php', }, '*'); @@ -74,11 +74,11 @@ function handleResponse(e) { window.addEventListener('message', handleResponse); ``` -Sandbox accepts messages in format `{ "type": , "requestId": , ...data : }` and sends back messages in the same format. At the moment, you need to implement the protocol on your own as there isn't yet JavaScript library to automate that. This page will be updated as soon as one is released. +Playground accepts messages in format `{ "type": , "requestId": , ...data : }` and sends back messages in the same format. At the moment, you need to implement the protocol on your own as there isn't yet JavaScript library to automate that. This page will be updated as soon as one is released. -Sandbox understands the following messages: +Playground understands the following messages: -* `{"type": "is_booted", "requestId": }` – Replies with true if the Sandbox is loaded and ready for messages. +* `{"type": "is_booted", "requestId": }` – Replies with true if the Playground is loaded and ready for messages. * `{"type": "go_to", "path": }` – Navigates to the requested path. * `{"type": "rpc", "method": , "args": , "requestId": }` – Calls one of the following functions: * `run(phpCode: string):` Promise<`{ exitCode: number; stdout: ArrayBuffer; stderr: string[]; }`> @@ -90,10 +90,10 @@ Sandbox understands the following messages: * `listFiles(path: string):` Promise * `isDir(path: string):` Promise -You will receive the following messages from Sandbox: +You will receive the following messages from Playground: * `{ "type": "response", "requestId": , "data": }` – A response to the message you sent earlier, identified by a unique requestId . -* `{ "type": "new_path", "path": }` – Whenever a new page is loaded in the Sandbox. +* `{ "type": "new_path", "path": }` – Whenever a new page is loaded in the Playground. ## WordPress web bundler @@ -115,13 +115,13 @@ The command outputs two files: * `build/wp.js` – the JavaScript loader for `wp.data` * `build/wp.data` – the WordPress data bundle consisting of concatenated contents of all WordPress files -Most of the work is done in the [relevant Dockerfile](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/wordpress/Dockerfile) – consult that file for more details. You can also customize the default WordPress installation by modifying that Dockerfile. +Most of the work is done in the [relevant Dockerfile](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/wordpress/Dockerfile) – consult that file for more details. You can also customize the default WordPress installation by modifying that Dockerfile. ## WordPress-specific setup for the Worker Thread and the Service Worker. -As seen in the [php-wasm-browser package documentation](https://github.com/WordPress/wordpress-sandbox/blob/trunk/docs/using-php-in-the-browser.md), running PHP in the browser requires a Worker Thread and a Service Worker. +As seen in the [php-wasm-browser package documentation](https://github.com/WordPress/wordpress-playground/blob/trunk/docs/using-php-in-the-browser.md), running PHP in the browser requires a Worker Thread and a Service Worker. -This package provides both, see [worker-thread.ts](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/worker-thread.ts) and [service-worker.ts](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/service-worker.ts). The browser expects each to be a separate script so they are not bundled with the main project. Instead, each is its own bundle built into `build/` directory. +This package provides both, see [worker-thread.ts](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/worker-thread.ts) and [service-worker.ts](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/service-worker.ts). The browser expects each to be a separate script so they are not bundled with the main project. Instead, each is its own bundle built into `build/` directory. WordPress and PHP are both initialized in the Worker Thread. The main application starts the Worker Thread using the `bootWordPress` function: @@ -159,7 +159,7 @@ For more details, see the `SpawnedWorkerThread` reference manual page and the ar ### Logging the user in -`wordpress-sandbox` provides helpers to automate common use-cases, like logging the user in: +`wordpress-playground` provides helpers to automate common use-cases, like logging the user in: ```js import { login } from './macros'; @@ -189,4 +189,4 @@ await installPlugin(workerThread, pluginFile); ## A PHP proxy to download plugins and themes from the WordPress.org directory -The browser cannot simply download a WordPress theme or plugin zip file from the wordpress.org directory because of the cross-origin request policy restrictions. This package provides a [PHP proxy script](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/plugin-proxy.php) that exposes plugins and themes on the same domain where WordPress Sandbox is hosted. +The browser cannot simply download a WordPress theme or plugin zip file from the wordpress.org directory because of the cross-origin request policy restrictions. This package provides a [PHP proxy script](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/plugin-proxy.php) that exposes plugins and themes on the same domain where WordPress Playground is hosted. diff --git a/esbuild.js b/esbuild.js index 5c5e6263e5..6ec990716d 100644 --- a/esbuild.js +++ b/esbuild.js @@ -72,15 +72,15 @@ async function main() { WASM_WORKER_THREAD_SCRIPT_URL: JSON.stringify(workerThreadScript), WASM_WORKER_BACKEND: JSON.stringify(wasmWorkerBackend), WP_JS_HASH: JSON.stringify( - hashFiles([`packages/wordpress-sandbox/build-wp/wp.js`]) + hashFiles([`packages/wordpress-playground/build-wp/wp.js`]) ), PHP_JS_HASH: JSON.stringify( hashFiles([`packages/php-wasm/build-wasm/php.js`]) ), }, entryPoints: { - 'worker-thread': 'src/wordpress-sandbox/worker-thread.ts', - app: 'src/wordpress-sandbox/index.tsx', + 'worker-thread': 'src/wordpress-playground/worker-thread.ts', + app: 'src/wordpress-playground/index.tsx', 'wordpress-plugin-ide': 'src/wordpress-plugin-ide/index.ts', react: 'react', 'react-dom': 'react-dom', @@ -94,7 +94,7 @@ async function main() { build({ ...baseConfig, entryPoints: { - 'service-worker': 'src/wordpress-sandbox/service-worker.ts', + 'service-worker': 'src/wordpress-playground/service-worker.ts', 'setup-fast-refresh-runtime': 'src/wordpress-plugin-ide/bundler/react-fast-refresh/setup-react-refresh-runtime.js', }, @@ -115,7 +115,7 @@ async function main() { console.log(''); console.log('Static files copied: '); mapGlob(`src/*/*.html`, buildHTMLFile); - mapGlob(`src/wordpress-sandbox/bundling/test/*.html`, buildHTMLFile); + mapGlob(`src/wordpress-playground/bundling/test/*.html`, buildHTMLFile); mapGlob(`node_modules/react/umd/react.development.js`, copyToDist); mapGlob(`node_modules/react-dom/umd/react-dom.development.js`, copyToDist); diff --git a/gulpfile.js b/gulpfile.js index f06a85cd96..72544db12c 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -6,7 +6,7 @@ const { spawnSync } = require('child_process'); const { build: buildWordPress, -} = require('./src/wordpress-sandbox/wordpress/gulpfile'); +} = require('./src/wordpress-playground/wordpress/gulpfile'); const { build: buildPHP } = require('./src/php-wasm/wasm/gulpfile'); const outputDir = path.join(__dirname, 'build'); @@ -59,9 +59,9 @@ function buildDocs(cb) { dtsPath('php-wasm-browser/index.d.ts'), dtsPath('php-wasm-browser/service-worker/worker-library.d.ts'), dtsPath('php-wasm-browser/worker-thread/worker-library.d.ts'), - dtsPath('wordpress-sandbox/index.d.ts'), - dtsPath('wordpress-sandbox/service-worker.d.ts'), - dtsPath('wordpress-sandbox/worker-thread.d.ts'), + dtsPath('wordpress-playground/index.d.ts'), + dtsPath('wordpress-playground/service-worker.d.ts'), + dtsPath('wordpress-playground/worker-thread.d.ts'), dtsPath('wordpress-plugin-ide/index.d.ts'), '-o', path.join(__dirname, 'docs', 'api'), diff --git a/mkdocs.yml b/mkdocs.yml index 2ad542b11e..26feaeb006 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,8 @@ -site_name: WordPress Sandbox +site_name: WordPress Playground theme: name: readthedocs -repo_url: https://github.com/WordPress/wordpress-sandbox +repo_url: https://github.com/WordPress/wordpress-playground edit_uri: blob/trunk/docs/ nav: @@ -13,7 +13,7 @@ nav: - API Reference: - php-wasm Reference: api/php-wasm.md - php-wasm-browser Reference: api/php-wasm-browser.md - - wordpress-sandbox Reference: api/wordpress-sandbox.md + - wordpress-playground Reference: api/wordpress-playground.md # markdown_extensions: # - meta diff --git a/scripts/postprocess-md-docs.js b/scripts/postprocess-md-docs.js index dd93c25f4c..22e44ca8e9 100644 --- a/scripts/postprocess-md-docs.js +++ b/scripts/postprocess-md-docs.js @@ -2,7 +2,7 @@ const fs = require('fs'); const path = require('path'); const DOCS_ABSOLUTE_URL = - 'https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs/'; + 'https://github.com/WordPress/wordpress-playground/tree/trunk/docs/'; const REPO_ROOT_PATH = path.dirname(__dirname); const TARGET_DIR = path.join(REPO_ROOT_PATH, 'docs'); @@ -14,7 +14,7 @@ const mdFiles = { './docs/index.md': 'index.md', './src/php-wasm/README.md': 'using-php-in-javascript.md', './src/php-wasm-browser/README.md': 'using-php-in-the-browser.md', - './src/wordpress-sandbox/README.md': 'using-wordpress-in-the-browser.md', + './src/wordpress-playground/README.md': 'using-wordpress-in-the-browser.md', './src/wordpress-plugin-ide/README.md': 'wordpress-plugin-ide.md', }; console.log(`Building the markdown files...`); diff --git a/src/php-wasm-browser/README.md b/src/php-wasm-browser/README.md index fb21b353e9..7b9c787787 100644 --- a/src/php-wasm-browser/README.md +++ b/src/php-wasm-browser/README.md @@ -1,6 +1,6 @@ # PHP in the browser -[API Reference](https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs/api/php-wasm-browser.md) +[API Reference](https://github.com/WordPress/wordpress-playground/tree/trunk/docs/api/php-wasm-browser.md) `php-wasm` makes running PHP code in JavaScript easy, but running PHP websites in the browser is more complex than just executing some code. @@ -27,7 +27,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. @@ -98,7 +98,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: @@ -172,7 +172,7 @@ The main application controls the worker thread by sending and receiving message Exchanging messages is the only way to control the worker threads. Remember – it is separate programs. The main app cannot access any functions or variables defined inside of the worker thread. -Conveniently, [spawnPHPWorkerThread](https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs/api/php-wasm-browser.spawnphpworkerthread.md) returns an easy-to-use API object that exposes specific worker thread features and handles the message exchange internally. +Conveniently, [spawnPHPWorkerThread](https://github.com/WordPress/wordpress-playground/tree/trunk/docs/api/php-wasm-browser.spawnphpworkerthread.md) returns an easy-to-use API object that exposes specific worker thread features and handles the message exchange internally. #### Worker thread implementation @@ -190,7 +190,7 @@ the heavy lifting. Here's its documentation: -initializeWorkerThread(config: [WorkerThreadConfiguration](https:/github.com/WordPress/wordpress-sandbox/tree/trunk/docs/api/php-wasm-browser.workerthreadconfiguration.md)): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)> +initializeWorkerThread(config: [WorkerThreadConfiguration](https:/github.com/WordPress/wordpress-playground/tree/trunk/docs/api/php-wasm-browser.workerthreadconfiguration.md)): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)> - `config` – The worker thread configuration. The backend object to communicate with the parent thread. @@ -240,7 +240,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: @@ -400,7 +400,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: diff --git a/src/php-wasm/README.md b/src/php-wasm/README.md index 36b630901c..4bc07ba4b6 100644 --- a/src/php-wasm/README.md +++ b/src/php-wasm/README.md @@ -1,6 +1,6 @@ # PHP in JavaScript -[API Reference](https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs/api/php-wasm.md) +[API Reference](https://github.com/WordPress/wordpress-playground/tree/trunk/docs/api/php-wasm.md) This package enables running PHP in Javascript: @@ -20,7 +20,7 @@ console.log(php.run(`(\    phpLoaderModule: [any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any), \ -   runtime: [JavascriptRuntime](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.javascriptruntime.md), \ +   runtime: [JavascriptRuntime](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.javascriptruntime.md), \    phpModuleArgs?: [any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any), \    dataDependenciesModules?: [any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)[]\ -): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[PHP](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.php.md)> +): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[PHP](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.php.md)> - `phpLoaderModule` – The ESM-wrapped Emscripten module. Consult the Dockerfile for the build process. - `runtime` – The current JavaScript environment. One of: NODE, WEB, or WEBWORKER. @@ -232,7 +232,7 @@ A fake PHP server that handles HTTP requests but does not bind to any port. ## Constructors -### PHPServer(php: [PHP](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.php.md), config: [PHPServerConfigation](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.phpserverconfigation.md)) +### PHPServer(php: [PHP](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.php.md), config: [PHPServerConfigation](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.phpserverconfigation.md)) - `php` – The PHP instance. - `config` – Server configuration. @@ -242,11 +242,11 @@ Constructs a new instance of the `PHPServer` class ## Properties - `absoluteUrl` readonly [string](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean) – The absolute URL of this PHPServer instance. -- `php` [PHP](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.php.md) – The PHP instance +- `php` [PHP](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.php.md) – The PHP instance ## Methods -### request(request: [PHPRequest](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.phprequest.md)): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[PHPResponse](https:/github.com/WordPress/wordpress-sandbox/blob/trunk/docs/api/php-wasm.phpresponse.md)> +### request(request: [PHPRequest](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.phprequest.md)): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[PHPResponse](https:/github.com/WordPress/wordpress-playground/blob/trunk/docs/api/php-wasm.phpresponse.md)> - `request` – The request. - Returns: The response. diff --git a/src/php-wasm/wasm/build-assets/php7.4.patch b/src/php-wasm/wasm/build-assets/php7.4.patch index 1d14d77eac..31d04b9ac3 100644 --- a/src/php-wasm/wasm/build-assets/php7.4.patch +++ b/src/php-wasm/wasm/build-assets/php7.4.patch @@ -151,7 +151,7 @@ diff --git a/php-src/ext/standard/file.c b/php-src/ext/standard/file.c goto safe_to_copy; break; case 0: -+ // Fix for https://github.com/WordPress/wordpress-sandbox/issues/54: ++ // Fix for https://github.com/WordPress/wordpress-playground/issues/54: + // Problem: Calling copy() on an empty source file crashes the JavaScript + // runtime. + // Solution: Avoid copying empty files. Just create create an empty diff --git a/src/typescript-reference-doc-generator/package.json b/src/typescript-reference-doc-generator/package.json index 2f6d571e6e..004c040660 100644 --- a/src/typescript-reference-doc-generator/package.json +++ b/src/typescript-reference-doc-generator/package.json @@ -10,14 +10,14 @@ "wasm", "WebAssembly" ], - "homepage": "https://github.com/WordPress/wordpress-sandbox/tree/HEAD/packages/wordpress-sandbox", + "homepage": "https://github.com/WordPress/wordpress-playground/tree/HEAD/packages/wordpress-playground", "repository": { "type": "git", - "url": "https://github.com/WordPress/wordpress-sandbox.git", + "url": "https://github.com/WordPress/wordpress-playground.git", "directory": "packages/typescript-reference-doc-generator" }, "bugs": { - "url": "https://github.com/WordPress/wordpress-sandbox/issues" + "url": "https://github.com/WordPress/wordpress-playground/issues" }, "engines": { "node": ">=12" diff --git a/src/wordpress-sandbox/.htaccess b/src/wordpress-playground/.htaccess similarity index 100% rename from src/wordpress-sandbox/.htaccess rename to src/wordpress-playground/.htaccess diff --git a/src/wordpress-sandbox/README.md b/src/wordpress-playground/README.md similarity index 68% rename from src/wordpress-sandbox/README.md rename to src/wordpress-playground/README.md index 39de52aa66..b2fb651732 100644 --- a/src/wordpress-sandbox/README.md +++ b/src/wordpress-playground/README.md @@ -1,24 +1,24 @@ # WordPress in the browser -[API Reference](https://github.com/WordPress/wordpress-sandbox/tree/trunk/docs/api/wordpress-sandbox.md) +[API Reference](https://github.com/WordPress/wordpress-playground/tree/trunk/docs/api/wordpress-playground.md) -This 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. +This 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. -The `wordpress-sandbox` package consists of: +The `wordpress-playground` package 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 - A PHP proxy to download plugins and themes from the WordPress.org directory -## Embeddable sandbox web page +## Embeddable playground web page All parts of this repository come together in the `wordpress.html` page where WordPress is loaded and displayed. -### Embedding WordPress Sandbox on other websites +### 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 ` ``` -### Controlling the embedded WordPress Sandbox via JavaScript API +### Controlling the embedded WordPress Playground via JavaScript API **The JavaScript API is an early preview and will likely evolve in the future.** -The embedded Sandbox can be controlled from JavaScript via `window.postMessage` if you used the `rpc=1` option: +The embedded Playground can be controlled from JavaScript via `window.postMessage` if you used the `rpc=1` option: ```js -// Ask the Sandbox whether it has finished booting: -document.querySelector('#sandbox').contentWindow.postMessage({ +// Ask the Playground whether it has finished booting: +document.querySelector('#playground').contentWindow.postMessage({ type: 'is_booted', requestId: 1 }, '*'); -// Receive the messages from Sandbox: +// Receive the messages from Playground: function handleResponse(e) { if(e.data.type === 'response' && e.data.requestId === 1 && e.data.response === true) { - // Navigate to wp-admin if the Sandbox was booted: - document.querySelector('#sandbox').contentWindow.postMessage({ + // Navigate to wp-admin if the Playground was booted: + document.querySelector('#playground').contentWindow.postMessage({ type: 'go_to', path: '/wp-admin/index.php', }, '*'); @@ -73,11 +73,11 @@ function handleResponse(e) { window.addEventListener('message', handleResponse); ``` -Sandbox accepts messages in format `{ "type": , "requestId": , ...data : }` and sends back messages in the same format. At the moment, you need to implement the protocol on your own as there isn't yet JavaScript library to automate that. This page will be updated as soon as one is released. +Playground accepts messages in format `{ "type": , "requestId": , ...data : }` and sends back messages in the same format. At the moment, you need to implement the protocol on your own as there isn't yet JavaScript library to automate that. This page will be updated as soon as one is released. -Sandbox understands the following messages: +Playground understands the following messages: -* `{"type": "is_booted", "requestId": }` – Replies with true if the Sandbox is loaded and ready for messages. +* `{"type": "is_booted", "requestId": }` – Replies with true if the Playground is loaded and ready for messages. * `{"type": "go_to", "path": }` – Navigates to the requested path. * `{"type": "rpc", "method": , "args": , "requestId": }` – Calls one of the following functions: * `run(phpCode: string):` Promise<`{ exitCode: number; stdout: ArrayBuffer; stderr: string[]; }`> @@ -89,10 +89,10 @@ Sandbox understands the following messages: * `listFiles(path: string):` Promise * `isDir(path: string):` Promise -You will receive the following messages from Sandbox: +You will receive the following messages from Playground: * `{ "type": "response", "requestId": , "data": }` – A response to the message you sent earlier, identified by a unique requestId . -* `{ "type": "new_path", "path": }` – Whenever a new page is loaded in the Sandbox. +* `{ "type": "new_path", "path": }` – Whenever a new page is loaded in the Playground. ## WordPress web bundler @@ -114,13 +114,13 @@ The command outputs two files: * `build/wp.js` – the JavaScript loader for `wp.data` * `build/wp.data` – the WordPress data bundle consisting of concatenated contents of all WordPress files -Most of the work is done in the [relevant Dockerfile](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/wordpress/Dockerfile) – consult that file for more details. You can also customize the default WordPress installation by modifying that Dockerfile. +Most of the work is done in the [relevant Dockerfile](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/wordpress/Dockerfile) – consult that file for more details. You can also customize the default WordPress installation by modifying that Dockerfile. ## WordPress-specific setup for the Worker Thread and the Service Worker. -As seen in the [php-wasm-browser package documentation](https://github.com/WordPress/wordpress-sandbox/blob/trunk/docs/using-php-in-the-browser.md), running PHP in the browser requires a Worker Thread and a Service Worker. +As seen in the [php-wasm-browser package documentation](https://github.com/WordPress/wordpress-playground/blob/trunk/docs/using-php-in-the-browser.md), running PHP in the browser requires a Worker Thread and a Service Worker. -This package provides both, see [worker-thread.ts](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/worker-thread.ts) and [service-worker.ts](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/service-worker.ts). The browser expects each to be a separate script so they are not bundled with the main project. Instead, each is its own bundle built into `build/` directory. +This package provides both, see [worker-thread.ts](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/worker-thread.ts) and [service-worker.ts](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/service-worker.ts). The browser expects each to be a separate script so they are not bundled with the main project. Instead, each is its own bundle built into `build/` directory. WordPress and PHP are both initialized in the Worker Thread. The main application starts the Worker Thread using the `bootWordPress` function: @@ -158,7 +158,7 @@ For more details, see the `SpawnedWorkerThread` reference manual page and the ar ### Logging the user in -`wordpress-sandbox` provides helpers to automate common use-cases, like logging the user in: +`wordpress-playground` provides helpers to automate common use-cases, like logging the user in: ```js import { login } from './macros'; @@ -188,4 +188,4 @@ await installPlugin(workerThread, pluginFile); ## A PHP proxy to download plugins and themes from the WordPress.org directory -The browser cannot simply download a WordPress theme or plugin zip file from the wordpress.org directory because of the cross-origin request policy restrictions. This package provides a [PHP proxy script](https://github.com/WordPress/wordpress-sandbox/blob/trunk/src/wordpress-sandbox/plugin-proxy.php) that exposes plugins and themes on the same domain where WordPress Sandbox is hosted. +The browser cannot simply download a WordPress theme or plugin zip file from the wordpress.org directory because of the cross-origin request policy restrictions. This package provides a [PHP proxy script](https://github.com/WordPress/wordpress-playground/blob/trunk/src/wordpress-playground/plugin-proxy.php) that exposes plugins and themes on the same domain where WordPress Playground is hosted. diff --git a/src/wordpress-sandbox/boot.ts b/src/wordpress-playground/boot.ts similarity index 94% rename from src/wordpress-sandbox/boot.ts rename to src/wordpress-playground/boot.ts index 152cbee2da..b56494837b 100644 --- a/src/wordpress-sandbox/boot.ts +++ b/src/wordpress-playground/boot.ts @@ -40,7 +40,7 @@ function assertNotInfiniteLoadingLoop() { } catch (e) {} if (isBrowserInABrowser) { throw new Error( - 'The service worker did not load correctly. This is a bug, please report it on https://github.com/WordPress/wordpress-sandbox/issues' + 'The service worker did not load correctly. This is a bug, please report it on https://github.com/WordPress/wordpress-playground/issues' ); } (window as any).IS_WASM_WORDPRESS = true; diff --git a/src/wordpress-sandbox/config.ts b/src/wordpress-playground/config.ts similarity index 100% rename from src/wordpress-sandbox/config.ts rename to src/wordpress-playground/config.ts diff --git a/src/wordpress-sandbox/index.tsx b/src/wordpress-playground/index.tsx similarity index 100% rename from src/wordpress-sandbox/index.tsx rename to src/wordpress-playground/index.tsx diff --git a/src/wordpress-sandbox/plugin-proxy.php b/src/wordpress-playground/plugin-proxy.php similarity index 100% rename from src/wordpress-sandbox/plugin-proxy.php rename to src/wordpress-playground/plugin-proxy.php diff --git a/src/wordpress-sandbox/progress-observer.ts b/src/wordpress-playground/progress-observer.ts similarity index 100% rename from src/wordpress-sandbox/progress-observer.ts rename to src/wordpress-playground/progress-observer.ts diff --git a/src/wordpress-sandbox/promise-queue.ts b/src/wordpress-playground/promise-queue.ts similarity index 100% rename from src/wordpress-sandbox/promise-queue.ts rename to src/wordpress-playground/promise-queue.ts diff --git a/src/wordpress-sandbox/requests_transport_fetch.php b/src/wordpress-playground/requests_transport_fetch.php similarity index 100% rename from src/wordpress-sandbox/requests_transport_fetch.php rename to src/wordpress-playground/requests_transport_fetch.php diff --git a/src/wordpress-sandbox/service-worker.ts b/src/wordpress-playground/service-worker.ts similarity index 100% rename from src/wordpress-sandbox/service-worker.ts rename to src/wordpress-playground/service-worker.ts diff --git a/src/wordpress-sandbox/wordpress.html b/src/wordpress-playground/wordpress.html similarity index 99% rename from src/wordpress-sandbox/wordpress.html rename to src/wordpress-playground/wordpress.html index 9bf7598fbb..78e5bdfe20 100644 --- a/src/wordpress-sandbox/wordpress.html +++ b/src/wordpress-playground/wordpress.html @@ -1,7 +1,7 @@ - WordPress Sandbox + WordPress Playground