Paquetes PHP.wasm

Los paquetes npm de PHP.wasm separan la API compartida de JavaScript, la configuración específica de cada plataforma y los binarios PHP compilados. La mayoría de las aplicaciones deberían utilizar un adaptador de plataforma. En cambio, las aplicaciones que prioricen una instalación más pequeña pueden cargar un paquete específico para una versión mediante la API de bajo nivel.

Capas de paquetes

Paquete	Responsabilidad
@php-wasm/universal	Proporciona la clase PHP independiente del entorno, loadPHPRuntime() y las API compartidas de solicitudes y del sistema de archivos. No selecciona una compilación para Node.js ni para el navegador.
@php-wasm/node	Proporciona loadNodeRuntime(version) y la configuración del entorno de ejecución específica de Node.js, incluidas las funciones de red, el bloqueo de archivos y las utilidades del sistema de archivos.
@php-wasm/web	Proporciona loadWebRuntime(version) y el entorno de ejecución, las funciones de red, el almacenamiento y las utilidades para workers específicos del navegador.
@php-wasm/node-X-Y y @php-wasm/web-X-Y	Contienen los binarios WebAssembly y los cargadores para una versión secundaria de PHP, además de los artefactos de extensiones correspondientes a esa versión cuando están disponibles.

Una aplicación crea el objeto PHP a partir de @php-wasm/universal. El adaptador de Node.js o web configura el entorno, selecciona una versión de PHP e importa el paquete correspondiente a esa versión. Por ejemplo, loadNodeRuntime('8.4') selecciona @php-wasm/node-8-4.

La API utiliza versiones con punto, como 8.4, mientras que los nombres de los paquetes npm utilizan un sufijo con guion, como 8-4.

Cargadores de plataforma prácticos

Utiliza un adaptador de plataforma cuando necesites sus integraciones con el entorno de ejecución o quieras seleccionar distintas versiones de PHP durante la ejecución. Para Node.js:

npm install @php-wasm/universal @php-wasm/node

import { PHP } from '@php-wasm/universal';
import { loadNodeRuntime } from '@php-wasm/node';

const php = new PHP(await loadNodeRuntime('8.4'));

En un navegador, utiliza @php-wasm/web y loadWebRuntime('8.4') en su lugar.

Los adaptadores de plataforma pueden seleccionar cualquiera de las versiones compatibles de PHP, y su grafo de dependencias publicado incluye los paquetes correspondientes a esas versiones. Esto resulta práctico, pero no produce la instalación más pequeña cuando una aplicación solo necesita una versión de PHP.

Cargar directamente una versión de PHP

Para obtener la menor huella de dependencias, omite el adaptador de plataforma e instala @php-wasm/universal junto con un paquete específico para una versión:

npm install @php-wasm/universal @php-wasm/node-8-4

Estos paquetes se publican juntos. Mantén alineadas sus versiones de publicación en npm.

A continuación, carga su módulo compilado mediante la API de bajo nivel:

import { PHP, loadPHPRuntime } from '@php-wasm/universal';
import { getPHPLoaderModule } from '@php-wasm/node-8-4';

const loaderModule = await getPHPLoaderModule();
const runtimeId = await loadPHPRuntime(loaderModule);
const php = new PHP(runtimeId);

const response = await php.runStream({
	code: '<?php echo "Hello from PHP " . PHP_VERSION;',
});
console.log(await response.stdoutText);

Para una compilación de navegador, utiliza el paquete correspondiente, como @php-wasm/web-8-4, con el mismo flujo de getPHPLoaderModule() y loadPHPRuntime(). Configura el empaquetador del navegador para emitir como recursos los archivos .wasm y .so importados, tal como se describe en la guía de empaquetadores de @php-wasm/web. Adapta las referencias a paquetes de esa configuración al nombre específico de la versión; por ejemplo, excluye @php-wasm/web-8-4 en lugar de @php-wasm/web.

En este caso, una huella más reducida significa instalar una sola versión secundaria de PHP en lugar de toda la matriz compatible. Cada paquete de versión sigue incluyendo las variantes compiladas y los artefactos correspondientes que requiere esa versión de PHP.

Este enfoque directo es intencionadamente de más bajo nivel. Omite la configuración que realizan loadNodeRuntime() o loadWebRuntime(), incluidas las funciones de red de la plataforma, el bloqueo de archivos de Node.js, la carga de extensiones y otras integraciones específicas del entorno. Utilízalo cuando la API compartida de PHP y el sistema de archivos en memoria sean suficientes, o cuando tu aplicación proporcione por sí misma la configuración necesaria de Emscripten.

Consulta las versiones compatibles de PHP para elegir el sufijo de paquete correspondiente.

¿Qué enfoque debes elegir?

• Utiliza @php-wasm/node o @php-wasm/web para disponer de la configuración del entorno de ejecución y las utilidades específicas de la plataforma, además de la API más sencilla para seleccionar versiones.
• Carga @php-wasm/node-X-Y o @php-wasm/web-X-Y directamente cuando el tamaño de la instalación sea más importante que las ventajas del adaptador de plataforma.