Support staging PHP.wasm side modules

Author: adamziel

packages/php-wasm/node/README.md

@@ -63,6 +63,9 @@ URL. Relative local paths are resolved from the current working directory.
 Relative artifact files in the manifest are resolved against the manifest
 location.
 
+Set `loadWithIniDirective: false` to stage a Wasm artifact without registering
+it in php.ini.
+
 External extensions are only supported when the Node.js runtime has JSPI
 available. Asyncify support is limited to the bundled extensions shipped with
 this package.

packages/php-wasm/node/src/test/with-php-extensions.spec.ts

@@ -105,6 +105,54 @@ describe('withPHPExtensions', () => {
 		).rejects.toThrow('External PHP extensions require JSPI');
 	});
 
+	it('stages extension artifacts without adding a php.ini scan dir', async () => {
+		const tempDir = await mkdtemp(
+			path.join(tmpdir(), 'php-wasm-extension-')
+		);
+		try {
+			const extensionBytes = new Uint8Array([1, 2, 3]);
+			await writeFile(
+				path.join(tempDir, 'sqlite_markdown.so'),
+				extensionBytes
+			);
+			await writeFile(
+				path.join(tempDir, 'manifest.json'),
+				JSON.stringify({
+					name: 'sqlite_markdown',
+					artifacts: [
+						{
+							phpVersion: '8.4',
+							sourcePath: 'sqlite_markdown.so',
+						},
+					],
+				})
+			);
+
+			const options = await withPHPExtensions('8.4', 'jspi', {}, [
+				{
+					source: {
+						format: 'manifest',
+						manifestUrl: path.join(tempDir, 'manifest.json'),
+					},
+					loadWithIniDirective: false,
+				},
+			]);
+			const fs = createFakeFS();
+
+			expect(options.ENV?.['PHP_INI_SCAN_DIR']).toBeUndefined();
+			options.onRuntimeInitialized?.({ FS: fs } as any);
+
+			expect(
+				fs.files.get(`${PHP_EXTENSIONS_DIR}/sqlite_markdown.so`)
+			).toEqual(extensionBytes);
+			expect(
+				fs.files.has(`${PHP_EXTENSIONS_DIR}/sqlite_markdown.ini`)
+			).toBe(false);
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it('treats drive-letter-shaped strings as local paths, not URL schemes', () => {
 		const source = normalizeNodeExtensionSource({
 			format: 'manifest',

packages/php-wasm/universal/README.md

@@ -21,16 +21,15 @@ artifacts for the PHP version matrix:
 	"artifacts": [
 		{
 			"phpVersion": "8.4",
-			"file": "wp_mysql_parser-php8.4-jspi.so",
-			"sha256": "..."
+			"sourcePath": "wp_mysql_parser-php8.4-jspi.so"
 		}
 	]
 }
 ```
 
-`file` may be absolute, or relative to the manifest URL. If you pass an inline
-manifest instead of `manifestUrl`, pass `baseUrl` to choose where relative
-artifact files are resolved from.
+`sourcePath` may be absolute, or relative to the manifest URL. If you pass an
+inline manifest instead of `manifestUrl`, pass `baseUrl` to choose where
+relative artifact files are resolved from.
 
 Asyncify extension loading is reserved for bundled extensions shipped with the
 PHP.wasm packages, such as `intl`, `xdebug`, `redis`, and `memcached`.
@@ -40,7 +39,9 @@ PHP.wasm packages, such as `intl`, `xdebug`, `redis`, and `memcached`.
 `resolvePHPExtension()` turns bytes, a direct artifact URL, or a manifest into a
 `ResolvedPHPExtension`. `withResolvedPHPExtensions()` then augments Emscripten
 options so the extension `.so`, generated `.ini`, sidecar files, and environment
-variables are ready before PHP scans its `.ini` files.
+variables are ready before PHP scans its `.ini` files. When
+`loadWithIniDirective` is `false`, the `.so` and sidecar files are still staged
+but no `.ini` file or `PHP_INI_SCAN_DIR` entry is generated.
 
 ```ts
 import { resolvePHPExtension, withResolvedPHPExtensions } from '@php-wasm/universal';