Breaking: PHP: Remove NodePHP and WebPHP classes in favor of a single "PHP" class

[adamziel]

Warning

This is breaking change! Review the description below to assess the impact on your app.

Consolidates the BasePHP, NodePHP, and WebPHP classes into a single PHP class. This refactor reduces redundancy and clarifies the PHP handling process across different environments.

Examples

NodePHP

Before

import { NodePHP } from '@php-wasm/node';
const php = await NodePHP.load('8.0');

After

import { loadNodeRuntime } from '@php-wasm/node';
import { PHP } from '@php-wasm/universal';
const php = new PHP(await loadNodeRuntime('8.0'));

WebPHP

Before

import { WebPHP } from '@php-wasm/web';
const php = await WebPHP.loadRuntime('8.0');

After

import { loadWebRuntime } from '@php-wasm/web';
import { PHP } from '@php-wasm/universal';
const php = new PHP(await loadWebRuntime('8.0'));

Mounting

Before

php.useHostFilesystem();
// or 
php.mount( '/home/users/adam/my-dir', '/my-dir-in-vfs');

After

import { NodeFSMount, useHostFilesystem } from '@php-wasm/node';
useHostFilesystem( php );
php.mount( new NodeFSMount( '/home/users/adam/my-dir' ), '/my-dir-in-vfs' );

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 separate createPHP and createPHPRuntime callbacks just because Playground uses different classes in node.js and in the browser. With this PR, createPHP callback will no longer be needed anymore as bootWordPress() will just always create a new PHP() instance.

Public API Changes

• Removes BasePHP, NodePHP, and WebPHP classes in favor of a single PHP class exported from @php-wasm/universal
• php.useHostFilesystem() was removed in favor of a decoupled function useHostFilesystem( php ) available in @php-wasm/node.
• PHP.mount() signature changed from mount( hostPath: string, vfsPath: string ) to mount( mountable: Mountable, vfsPath: string )
• Moves WebPHPEndpoint from @php-wasm/web to @php-wasm/universal and renames it to PHPWorker. That class isn't specific to the web and could be easily used by Node workers.
• Removes the IsomorphicLocalPHP interface. The PHP class is now the source of truth for all derived worker, client, etc. implementations.
• Removes the createPhpInstance() option from bootWordPress( options ) in favor of always using the PHP class.
• Updates to Documentation: Adjusted examples and references in the documentation to reflect the new PHP class.
• Refactoring of Test Suites: Updated tests to work with the new class structure.

Testing instructions

Confirm all the CI checks pass – this PR includes an extensive refactor of all the tests.

Heads up @wojtekn @fluiddot @sejas

[adamziel]

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]

Thank you! Having a single PHP class will make things much cleaner and should make it easier to understand the code.