-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Port Query API and WebAssembly pages from the existing documentation #50
- Loading branch information
Showing
15 changed files
with
470 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
103 changes: 103 additions & 0 deletions
103
wp-content/html-pages/1_developer-apis/1_query-api.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,103 @@ | ||
<h1>Query API</h1> | ||
|
||
<!-- wp:paragraph --> | ||
<p>WordPress Playground exposes a simple API that you can use to configure the Playground in the browser.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>It works by passing configuration options as query parameters to the Playground URL. For example, to install the pendant theme, you would use the following URL:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code>https://playground.wordpress.net/?theme=pendant</code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>You can go ahead and try it out. The Playground will automatically install the theme and log you in as an admin. You may even embed this URL in your website using an <code><iframe></code> tag:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code><iframe src="https://playground.wordpress.net/?theme=pendant"></iframe></code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:heading --> | ||
<h2 class="wp-block-heading">Available options</h2> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:table --> | ||
<figure class="wp-block-table"><table class="has-fixed-layout"><thead><tr><th>Option</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>php</code></td><td><code>8.0</code></td><td>Loads the specified PHP version. Supported values: <code>7.0</code>, <code>7.1</code>, <code>7.2</code>, <code>7.3</code>, <code>7.4</code>, <code>8.0</code>, <code>8.1</code>, <code>8.2</code>, <code>8.3</code>, <code>latest</code></td></tr><tr><td><code>wp</code></td><td><code>latest</code></td><td>Loads the specified WordPress version. Supported values: The last three major WordPress versions. As of April 4, 2024, that's <code>6.3</code>, <code>6.4</code>, <code>6.5</code>. You can also use these values: <code>latest</code>, <code>nightly</code>, <code>beta</code></td></tr><tr><td><code>blueprint-url</code></td><td></td><td>The URL of the Blueprint that will be used to configure this Playground instance.</td></tr><tr><td><code>php-extension-bundle</code></td><td></td><td>Loads a bundle of PHP extensions. Supported bundles: <code>kitchen-sink</code> (for finfo, gd, mbstring, iconv, openssl, libxml, xml, dom, simplexml, xmlreader, xmlwriter), <code>light</code> (saves 6MB of downloads, loads none of the above extensions)</td></tr><tr><td><code>networking</code></td><td><code>yes</code> or <code>no</code></td><td>Enables or disables the networking support for Playground. Defaults to <code>no</code></td></tr><tr><td><code>plugin</code></td><td></td><td>Installs the specified plugin. Use the plugin name from the plugins directory URL, e.g. for a URL like <code>https://wordpress.org/plugins/wp-lazy-loading/</code>, the plugin name would be <code>wp-lazy-loading</code>. You can pre-install multiple plugins by saying <code>plugin=coblocks&plugin=wp-lazy-loading&…</code>. Installing a plugin automatically logs the user in as an admin</td></tr><tr><td><code>theme</code></td><td></td><td>Installs the specified theme. Use the theme name from the themes directory URL, e.g. for a URL like <code>https://wordpress.org/themes/disco/</code>, the theme name would be <code>disco</code>. Installing a theme automatically logs the user in as an admin</td></tr><tr><td><code>url</code></td><td><code>/wp-admin/</code></td><td>Load the specified initial page displaying WordPress</td></tr><tr><td><code>mode</code></td><td><code>seamless</code>, <code>browser</code>, or <code>browser-full-screen</code></td><td>Displays WordPress on a full-page or wraps it in a browser UI</td></tr><tr><td><code>lazy</code></td><td></td><td>Defer loading the Playground assets until someone clicks on the "Run" button</td></tr><tr><td><code>login</code></td><td><code>yes</code></td><td>Logs the user in as an admin. Set to <code>no</code> to not log in.</td></tr><tr><td><code>multisite</code></td><td><code>no</code></td><td>Enables the WordPress multisite mode.</td></tr><tr><td><code>storage</code></td><td></td><td>Selects the storage for Playground: <code>none</code> gets erased on page refresh, <code>browser</code> is stored in the browser, and <code>device</code> is stored in the selected directory on a device. The last two protect the user from accidentally losing their work upon page refresh.</td></tr><tr><td><code>import-site</code></td><td></td><td>Imports site files and database from a zip file specified by URL.</td></tr><tr><td><code>import-wxr</code></td><td></td><td>Imports site content from a WXR file specified by URL. It uses the WordPress Importer, so the default admin user must be logged in.</td></tr></tbody></table></figure> | ||
<!-- /wp:table --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>For example, the following code embeds a Playground with a preinstalled Gutenberg plugin, and opens the post editor:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code><iframe src="https://playground.wordpress.net/?plugin=gutenberg&url=/wp-admin/post-new.php&mode=seamless"> </iframe></code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>:::info CORS policy</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>To import files from a URL, such as a site zip package, they must be served with <code>Access-Control-Allow-Origin</code> header set. For reference, see: <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_response_headers">Cross-Origin Resource Sharing (CORS)</a>.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>:::</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading --> | ||
<h2 class="wp-block-heading">GitHub Export Options</h2> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The following additional query parameters may be used to pre-configure the GitHub export form:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:list --> | ||
<ul><!-- wp:list-item --> | ||
<li><code>gh-ensure-auth</code>: If set to <code>yes</code>, Playground will display a modal to ensure the<br>user is authenticated with GitHub before proceeding.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-repo-url</code>: The URL of the GitHub repository to export to.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-pr-action</code>: The action to take when exporting (create or update).</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-playground-root</code>: The root directory in the Playground to export from.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-repo-root</code>: The root directory in the repository to export to.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-content-type</code>: The content type of the export (plugin, theme, wp-content, custom-paths).</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-plugin</code>: Plugin path. When the content type is <code>plugin</code>, pre-select the plugin to export.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-theme</code>: Theme directory name. When the content type is <code>theme</code>, pre-select the theme to export.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-path</code>: A path relative to <code>ghexport-playground-root</code>. Can be provided multiple times. When the<br>content type is <code>custom-paths</code>, it pre-populates the list of paths to export.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-commit-message</code>: The commit message to use when exporting.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li><code>ghexport-allow-include-zip</code>: Whether to offer an option to include a zip file in the GitHub<br>export (yes, no). Optional. Defaults to <code>yes</code>.</li> | ||
<!-- /wp:list-item --></ul> | ||
<!-- /wp:list --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
<h1>Developer APIs</h1> | ||
|
160 changes: 160 additions & 0 deletions
160
wp-content/html-pages/2_architecture/4_webassembly-php/1_compiling-php.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,160 @@ | ||
<h1>Compiling PHP</h1> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The build pipeline lives in a <a href="https://github.com/WordPress/wordpress-playground/blob/trunk/src/packages/php-wasm/compile/Dockerfile"><code>Dockerfile</code></a>. In broad strokes, it:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:list --> | ||
<ul><!-- wp:list-item --> | ||
<li>Installs all the necessary linux packages (like <code>build-essential</code>)</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Downloads PHP and the required libraries, e.g. <code>sqlite3</code>.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Applies a few patches.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Compiles everything using <a href="https://emscripten.org/">Emscripten</a>, a drop-in replacement for the C compiler.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Compiles <code>php_wasm.c</code> – a convenient API for JavaScript.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Outputs a <code>php.wasm</code> file and one or more JavaScript loaders, depending on the configuration.</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Transforms the Emscripten's default <code>php.js</code> output into an ESM module with additional features.</li> | ||
<!-- /wp:list-item --></ul> | ||
<!-- /wp:list --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>To find out more about each step, refer directly to the <a href="https://github.com/WordPress/wordpress-playground/blob/trunk/src/packages/php-wasm/compile/Dockerfile">Dockerfile</a>.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading {"level":3} --> | ||
<h3 class="wp-block-heading">Building</h3> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>To build all PHP versions, run <code>npm run recompile:php:web</code> (or <code>php-wasm-node</code>) in the repository root. You'll find the output files in <code>packages/php-wasm/php-web/public</code>. To build a specific version, run <code>npm run recompile:php:web:kitchen-sink:8.0</code> or <code>npm run recompile:php:web:light:8.0</code> – depending on the build pack.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The build produces two files: <code>php.wasm</code> and <code>php.js</code>.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading {"level":3} --> | ||
<h3 class="wp-block-heading">PHP.wasm WebAssembly module</h3> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:heading {"level":4} --> | ||
<h4 class="wp-block-heading">PHP extensions</h4> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>PHP is built with several extensions listed in the <a href="https://github.com/WordPress/wordpress-playground/blob/trunk/src/packages/php-wasm/compile/Dockerfile"><code>Dockerfile</code></a>.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>Some extensions, like <code>zip</code>, can be turned on or off during the build. Others, like <code>sqlite3</code>, are hardcoded.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>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.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading {"level":4} --> | ||
<h4 class="wp-block-heading">C API exposed to JavaScript</h4> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The C API exposed to JavaScript lives in the <a href="https://github.com/WordPress/wordpress-playground/blob/trunk/src/packages/php-wasm/compile/build-assets/php_wasm.c"><code>php_wasm.c</code></a> file.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>Refer to the source code and the inline documentation in <a href="https://github.com/WordPress/wordpress-playground/blob/trunk/src/packages/php-wasm/compile/build-assets/php_wasm.c"><code>php_wasm.c</code></a> to learn more.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading {"level":4} --> | ||
<h4 class="wp-block-heading">Build configuration</h4> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The build is configurable via the <a href="https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg">Docker <code>--build-arg</code> feature</a>. You can set them up through the <code>build.js</code> script, just run this command to get the usage message:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code>npm run recompile:php:web</code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:heading {"level":3} --> | ||
<h3 class="wp-block-heading">PHP.js JavaScript module</h3> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The <code>php.js</code> file generated by the <a href="./03-wasm-php-compiling.md">WebAssembly PHP build pipeline</a> is <strong>not</strong> a vanilla Emscripten module. Instead, it's an ESM module that wraps the regular Emscripten output and adds some extra functionality.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>Here's the API it exposes:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code>// php.wasm size in bytes: | ||
export const dependenciesTotalSize = 5644199; | ||
|
||
// php.wasm filename: | ||
export const dependencyFilename = 'php.wasm'; | ||
|
||
// Run Emscripten's generated module: | ||
export default function (jsEnv, emscriptenModuleArgs) {}</code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The generated JavaScript module is not meant for direct use. Instead, it can be consumed through a <code>NodePHP</code> class in Node.js and a <code>WebPHP</code> class in the browser:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code>// In Node.js: | ||
const php = NodePHP.load('7.4'); | ||
|
||
// On the web: | ||
const php = await WebPHP.load('8.0');</code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>Both of these classes extend the <code>BasePHP</code> class exposed by the <code>@php-wasm/universal</code> package and implement the <code>UniversalPHP</code> interface that standardizes the API across all PHP environments.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:heading {"level":3} --> | ||
<h3 class="wp-block-heading">Loading the PHP runtime</h3> | ||
<!-- /wp:heading --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The load() method handles the entire PHP initialization pipeline. In particular, it:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:list --> | ||
<ul><!-- wp:list-item --> | ||
<li>Instantiates the Emscripten PHP module</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Wires it together with the data dependencies and loads them</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Ensures is all happens in a correct order</li> | ||
<!-- /wp:list-item --> | ||
|
||
<!-- wp:list-item --> | ||
<li>Waits until the entire loading sequence is finished</li> | ||
<!-- /wp:list-item --></ul> | ||
<!-- /wp:list --> |
40 changes: 40 additions & 0 deletions
40
wp-content/html-pages/2_architecture/4_webassembly-php/2_php-filesystem.html
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
<h1>PHP Filesystem</h1> | ||
|
||
<!-- wp:paragraph --> | ||
<p>The PHP module has its own filesystem separate from your computer's filesystem. It is provided by <a href="https://emscripten.org/docs/api_reference/Filesystem-API.html">Emscripten's FS library</a> and the default APIs is low-level and cumbersome to use. The <code>PHP</code> JavaScript class shipped with WordPress Playground wraps it with a more convenient higher-level API.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>In general, WordPress Playground uses an in-memory virtual filesystem.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>However, in Node.js, you can also mount a real directory from the host filesystem into the PHP filesystem.</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>Here's how to interact with the filesystem in WordPress Playground:</p> | ||
<!-- /wp:paragraph --> | ||
|
||
<!-- wp:code --> | ||
<pre class="wp-block-code"><code>// Recursively create a /var/www directory | ||
php.mkdirTree('/var/www'); | ||
|
||
console.log(php.fileExists('/var/www/file.txt')); | ||
// false | ||
|
||
php.writeFile('/var/www/file.txt', 'Hello from the filesystem!'); | ||
|
||
console.log(php.fileExists('/var/www/file.txt')); | ||
// true | ||
|
||
console.log(php.readFile('/var/www/file.txt')); | ||
// "Hello from the filesystem! | ||
|
||
// Delete the file: | ||
php.unlink('/var/www/file.txt');</code></pre> | ||
<!-- /wp:code --> | ||
|
||
<!-- wp:paragraph --> | ||
<p>For more details consult the BasePHP class directly – it has some great documentation strings.</p> | ||
<!-- /wp:paragraph --> |
Oops, something went wrong.