From 7afcf4bc71f6c759ffdec4372a0eb952553ff8be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= <adam@adamziel.com>
Date: Tue, 14 Oct 2025 01:42:43 +0200
Subject: [PATCH 1/2] [PHP.wasm] Document bundler configuration for the .dat
 file import in `@php-wasm/web`

Added instructions for using `@php-wasm/web` with bundlers like Vite. The `import dataFilename from './icudt741.dat';` like published in the package will typically trip up bundlers with their default configuration.

cc @fellyph @mho22 @brandonpayton
---
 packages/php-wasm/web/README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/packages/php-wasm/web/README.md b/packages/php-wasm/web/README.md
index 02f37d0d7f..6e8d1bf209 100644
--- a/packages/php-wasm/web/README.md
+++ b/packages/php-wasm/web/README.md
@@ -30,6 +30,39 @@ const response = await php.request({
 console.log(response.text);
 ```
 
+## Usage with bundlers
+
+If you use `@php-wasm/web` with a bundler such as Vite, you may see the following errors:
+
+```
+01:31:50 [vite] (client) error while updating dependencies:
+Error: Error during dependency optimization:
+
+✘ [ERROR] No loader is configured for ".dat" files: app/node_modules/@php-wasm/web/shared/icudt74l.dat
+
+    app/node_modules/@php-wasm/web/shared/icudt74l.js:1:25:
+      1 │ import dataFilename from './icudt74l.dat';
+```
+
+The `@php-wasm/web` package imports a non-JavaScript asset file using the import syntax. This ensures
+all the required dependencies may be tracked statically, but it creates an inconvenience for apps relying
+on bundlers.
+
+To resolve that error, you'll need to configure your bundler to resolve the import above to the URL
+of the `icudt74l.dat` in your app, e.g. `https://playground.wordpress.net/assets/icudt74l.dat`.
+
+In Vite, you can use the `assetsInclude` option:
+
+```js
+export default defineConfig({
+	assetsInclude: [/\.dat$/],
+});
+```
+
+Other bundlers will typically have analogous options or plugins. If you create a working configuration for
+WebPack, esbuild, or another bundler, feel free to propose a new configuration example for this README at
+https://github.com/WordPress/wordpress-playground/edit/trunk/packages/php-wasm/web/README.md
+
 ## Attribution
 
 `@php-wasm/web` started as a fork of the original PHP to WebAssembly build published by Oraoto in https://github.com/oraoto/pib and modified by Sean Morris in https://github.com/seanmorris/php-wasm.

From ba2798588ac40679debe23c18aaff18ffb615da2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= <adam@adamziel.com>
Date: Tue, 14 Oct 2025 01:56:29 +0200
Subject: [PATCH 2/2] Revise usage instructions and bundler options in README

Updated README to reflect changes in PHP loading and bundler configurations.
---
 packages/php-wasm/web/README.md | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/packages/php-wasm/web/README.md b/packages/php-wasm/web/README.md
index 6e8d1bf209..33d40fe492 100644
--- a/packages/php-wasm/web/README.md
+++ b/packages/php-wasm/web/README.md
@@ -6,18 +6,15 @@ Here's how to use it:
 
 ```js
 import { PHP } from '@php-wasm/web';
+import { loadWebRuntime } from '@php-wasm/web'
 
-// PHP.load() calls import('php.wasm') internally
+// loadWebRuntime() calls import('php.wasm') and import('icudt74l.dat') internally.
 // Your bundler must resolve import('php.wasm') as a static file URL.
 // If you use Webpack, you can use the file-loader to do so.
-const php = await PHP.load('8.0', {
-	requestHandler: {
-		documentRoot: '/www',
-	},
-});
+const php = new PHP(await loadWebRuntime('8.3'))
 
 // Create and run a script directly
-php.mkdirTree('/www');
+php.mkdir('/www');
 php.writeFile('/www/index.php', `<?php echo "Hello " . $_POST['name']; ?>`);
 await php.run({ scriptPath: './index.php' });
 
@@ -44,18 +41,32 @@ Error: Error during dependency optimization:
       1 │ import dataFilename from './icudt74l.dat';
 ```
 
-The `@php-wasm/web` package imports a non-JavaScript asset file using the import syntax. This ensures
+The `@php-wasm/web` package imports a few non-JavaScript assets file using the import syntax. This ensures
 all the required dependencies may be tracked statically, but it creates an inconvenience for apps relying
 on bundlers.
 
 To resolve that error, you'll need to configure your bundler to resolve the import above to the URL
 of the `icudt74l.dat` in your app, e.g. `https://playground.wordpress.net/assets/icudt74l.dat`.
 
-In Vite, you can use the `assetsInclude` option:
+In Vite, you can use the following options to support importing all the required assets types:
 
 ```js
 export default defineConfig({
-	assetsInclude: [/\.dat$/],
+	assetsInclude: [/\.dat$/, /\.wasm$/, /\.so$/, /\.la$/],
+	optimizeDeps: {
+		esbuildOptions: {
+			loader: {
+				'.dat': 'file',
+				'.wasm': 'file',
+				'.so': 'file',
+				'.la': 'file',
+			},
+		},
+	},
+	build: {
+		// outDir is required with the 'file' loader
+		outDir: path.resolve(workspaceRoot, 'dist'),
+	}
 });
 ```