[PHP WASM] Transfer ArrayBuffer instead of cloning in PHPResponse serialization (#3036)

epeicher · web-flow · commit ce96566bcbbd · 2025-12-15T13:16:58.000+01:00
Fix DataCloneError when handling large files by transferring the
ArrayBuffer instead of cloning it. This is more efficient and works with
detached buffers.

## Motivation for the change, related issues

STU-73

## Implementation details

Modified the `PHPResponse` transfer handler's `serialize` method in
`api.ts` to explicitly transfer the underlying `ArrayBuffer` instead of
cloning it.

Previously, the method returned an empty transferables array, causing
Comlink to clone the response data. For large files (e.g., 4.8GB
backups), this failed with `DataCloneError` when the ArrayBuffer had
already been transferred/detached upstream. The fix adds
`data.bytes.buffer` to the transferables array, enabling zero-copy
transfer regardless of the buffer's prior state. This resolves the
serialization error for large file downloads while also improving memory
efficiency.


## Testing Instructions (or ideally a Blueprint)

1. Create a site locally for example using Studio
2. Using the terminal, run the playground cli mounting the Studio
folder, for example using this command:
```
nx dev playground-cli server --mount-before-install=&lt;path-to-studio-site&gt;:/wordpress
```
Replacing `&lt;path-to-studio-site&gt;` with the root path of your Studio
site, I use the absolute path for that.
4. Open the URL that playground-cli provides and navigate to WP admin,
you can take the password from the Studio settings.
5. Install  All In One WP Migration plugin.
6. Upload &gt;2GB files to the site, you can use large media files for
that.
7. Export site to file using the plugin.
8. Download the file
9. Verify that the file can be downloaded successfully.
diff --git a/packages/php-wasm/universal/src/lib/api.ts b/packages/php-wasm/universal/src/lib/api.ts
@@ -218,7 +218,14 @@ function setupTransferHandlers() {
 			'exitCode' in obj &&
 			'httpStatusCode' in obj,
 		serialize(obj: PHPResponse): [PHPResponseData, Transferable[]] {
-			return [obj.toRawData(), []];
+			const data = obj.toRawData();
+			// Transfer the ArrayBuffer instead of cloning it to avoid
+			// "could not be cloned" errors when the buffer is detached
+			const transferables: Transferable[] = [];
+			if (data.bytes.buffer.byteLength > 0) {
+				transferables.push(data.bytes.buffer);
+			}
+			return [data, transferables];
 		},
 		deserialize(responseData: PHPResponseData): PHPResponse {
 			return PHPResponse.fromRawData(responseData);
