Skip to content
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.

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

Isomorphic PHP, Isomorphic Blueprints #214

Merged
merged 25 commits into from
Apr 24, 2023
Merged

Isomorphic PHP, Isomorphic Blueprints #214

merged 25 commits into from
Apr 24, 2023

Conversation

adamziel
Copy link
Collaborator

@adamziel adamziel commented Apr 23, 2023

Description

Generalizes Playground Blueprints from working with just the in-browser Playground API client to working:

  • On the web and in Node.js
  • With a local Playground object
  • With a remote Playground client

With this PR applied, all of the following login() calls are valid:

// In the browser
const phpInSameThread = await WebPHP.load( '7.4', { dataModules: [ 'wp.data' ] } );
await login( phpInSameThread );

const phpInWorker = await consumeAPI( playgroundIframe );
await login( phpInWorker );
// In node.js
const phpInSameThread = await NodePHP.load( '7.4' );
phpInSameThread.mount( '/wordpress', '/wordpress' );
await login( phpInSameThread );
// ^ @TODO: Still fails unless you provide a DOMParser polyfill

This opens the door to using Blueprints in the VS Code extension, wp-now, and other tools.

Implementation

Blueprint were initially implemented as a part of the browser API client in @wp-playground/client. This PR decouples them into an isomorphic @wp-playground/blueprints package that depends on @php-wasm/universal which is also isomorphic.

In other words, step handlers such as login(playground) used to require a PlaygroundClient instance, but now they can work with a UniversalPHP instance defined as follows:

type IsomorphicLocalPHP = { /* ... PHP methods ... */ }
// Remote<T> means every method of T now returns a promise
type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;

UniversalPHP is a type, not a class. It's a common core of all PHP implementations in other packages and provides methods like run(), request(), and writeFile(). @php-wasm/universal also provides a reference implementation of UniversalPHP called BasePHP.

BasePHP cannot be used directly. Instead, platform-specific packages @php-wasm/web and @php-wasm/node provide platform-specific implementations. The former exports WebPHP, which loads files using fetch(), and the latter exports NodePHP, which reads data directly from the host filesystem. Both implement the UniversalPHP interface and can be used with any Blueprint step.

Other notes

  • @php-wasm/universal, @wp-playground/client, and @wp-playground/blueprints are published as isomorphic ESM/CJS packages. @php-wasm/node is published as CJS only for now.

Follow-up work

  • @wp-playground/blueprints will need to be smart about providing a Node.js polyfill for new DOMParser() and fetch().

@adamziel adamziel force-pushed the isomorphic-helpers branch from 6650dcb to 2b11f8c Compare April 24, 2023 09:46
@adamziel adamziel marked this pull request as ready for review April 24, 2023 11:24
@adamziel adamziel changed the title Isomorphic Blueprints Isomorphic PHP, Isomorphic Blueprints Apr 24, 2023
@adamziel
Copy link
Collaborator Author

adamziel commented Apr 24, 2023

@dmsnell I'm going to merge this one, but that doesn't mean it's closed for feedback. Your suggestions were invaluable and made it a lot better – I'm happy to keep addressing them, only in a follow-up PR.

Oh, and it's a huge PR but I'm still going to merge the entire thing. Turning it into a series of commits would require quite a few intermediate scaffolds to keep the CI happy along the way. I hope it's not going to come up too much during future bisects!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants