Breaking: PHP: Remove NodePHP and WebPHP classes in favor of a single "PHP" class#1457
Merged
Breaking: PHP: Remove NodePHP and WebPHP classes in favor of a single "PHP" class#1457
Conversation
Closes #1399 Description TBD
adamziel
added a commit
that referenced
this pull request
May 23, 2024
Implements a `bootWordPress()` function aiming to provide a reliable and consistent boot pipeline for every Playground-based app, whether it's a browser app, server app, a VS Code extension, or anything else. As a nice side-effect, Playground can now boot not just from the custom minified WordPress builds, but also from the official WordPress releases! Related issue: #1398 ## How does it work? `bootWordPress()` ties together all the pieces from different Playground-based apps. [Boot flow diagram](#1379 (comment)) demonstrates the idea. A tl;dr pipeline is: * Mount resources (stage=before WordPress files) * Unzip WordPress, if that's requested * Mount resources (stage=before database setup) * Setup SQLite, MySQL (TODO), or rely on a mounted database * Run WordPress installer, if the site isn't installed yet Here's a usage example in a Node.js app: ```ts const requestHandler = await bootWordPress({ siteUrl: absoluteUrl, createPhpInstance() { return new NodePHP(); }, createPhpRuntime: async () => await NodePHP.loadRuntime(compiledBlueprint.versions.php), wordPressZip, sqliteIntegrationPluginZip: fetchSqliteIntegration(monitor), sapiName: 'cli', createFiles: { '/internal/shared/ca-bundle.crt': rootCertificates.join('\n'), }, phpIniEntries: { 'openssl.cafile': '/internal/shared/ca-bundle.crt', allow_url_fopen: '1', disable_functions: '', }, hooks: { async beforeWordPressFiles(php) { if (args.mountBeforeInstall) { mountResources(php, args.mountBeforeInstall); } }, }, }); ``` ## Testing instructions * Confirm all the CI checks work * Load the latest nightly **official WordPress build** into Playground: http://localhost:5400/website-server/?php=8.0&wp=http://localhost:5400/plugin-proxy.php?url=https://wordpress.org/nightly-builds/wordpress-latest.zip * Load the official WordPress 6.5 release into Playground: http://localhost:5400/website-server/?php=8.0&wp=http://localhost:5400/plugin-proxy.php?url=https://wordpress.org/latest.zip * Confirm Playground CLI still works: Run bun packages/playground/cli/src/cli.ts server --login and confirm it loads an installed WordPress. ## Follow-up work * Replace manual calls to `setupPlatformLevelMuPlugins()` in unit tests with `bootWordPress()` * Add unit tests to confirm boot works with minified WordPress build, official WordPress release, SQLite, MySQL. Test all the `BootOptions` and confirm PHP.ini directives are used, constants are created etc. * Remove the `createPhpInstance()` argument in favor of using just the `PHP` class – once #1457 merges * Figure out storing `debug.log` in the `configureErrorLogging` mu-plugin – right now it's stored in `/wordpress/wp-content` * Support more database modes: MySQL and `custom` where Playground relies on `db.php` brought in from * Replace hooks with a Mount data type that would have different implementations, like OPFS, Native FS, and Node FS – explorations started in #1457 * Once the API settles, document the usage for developers cc @brandonpayton @bgrgicak
adamziel
commented
May 23, 2024
| /* eslint-disable @typescript-eslint/no-namespace */ | ||
| /** Other WebAssembly declarations, for compatibility with older versions of Typescript */ | ||
|
|
||
| export namespace Emscripten { |
Collaborator
Author
There was a problem hiding this comment.
DefinitelyTyped types didn't play well the way we build rollup.d.ts – it's easier to ship a copy of these types. If that turns out to be a maintenance burden, let's reassess.
bgrgicak
approved these changes
May 24, 2024
Collaborator
bgrgicak
left a comment
There was a problem hiding this comment.
Thank you! Having a single PHP class will make things much cleaner and should make it easier to understand the code.
1 task
This was referenced Aug 23, 2024
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Warning
This is breaking change! Review the description below to assess the impact on your app.
Consolidates the
BasePHP,NodePHP, andWebPHPclasses into a singlePHPclass. This refactor reduces redundancy and clarifies the PHP handling process across different environments.Examples
NodePHP
Before
After
WebPHP
Before
After
Mounting
Before
After
Closes #1399
Motivation
First, the public API surface of all the PHP classes and interfaces is overly complex. This PR is a step towards simplifying it.
Second, in the Boot Protocol, PR the
bootWordPress()function requires separatecreatePHPandcreatePHPRuntimecallbacks just because Playground uses different classes in node.js and in the browser. With this PR,createPHPcallback will no longer be needed anymore asbootWordPress()will just always create anew PHP()instance.Public API Changes
BasePHP,NodePHP, andWebPHPclasses in favor of a single PHP class exported from@php-wasm/universalphp.useHostFilesystem()was removed in favor of a decoupled functionuseHostFilesystem( php )available in@php-wasm/node.PHP.mount()signature changed frommount( hostPath: string, vfsPath: string )tomount( mountable: Mountable, vfsPath: string )@php-wasm/webto@php-wasm/universaland renames it toPHPWorker. That class isn't specific to the web and could be easily used by Node workers.IsomorphicLocalPHPinterface. The PHP class is now the source of truth for all derived worker, client, etc. implementations.createPhpInstance()option frombootWordPress( options )in favor of always using the PHP class.PHPclass.Testing instructions
Confirm all the CI checks pass – this PR includes an extensive refactor of all the tests.
Heads up @wojtekn @fluiddot @sejas