Pacotes PHP.wasm

Os pacotes PHP.wasm no npm separam a API JavaScript compartilhada, a configuração específica da plataforma e os binários compilados do PHP. A maioria dos aplicativos deve usar um adaptador de plataforma. Já os aplicativos que priorizam uma instalação menor podem carregar um pacote específico por versão pela API de baixo nível.

Camadas de pacotes

Pacote	Responsabilidade
@php-wasm/universal	Fornece a classe PHP independente de ambiente, loadPHPRuntime() e as APIs compartilhadas de requisições e sistema de arquivos. Ele não seleciona uma build para Node.js ou navegador.
@php-wasm/node	Fornece loadNodeRuntime(version) e a configuração de runtime específica do Node.js, incluindo rede, bloqueio de arquivos e auxiliares do sistema de arquivos.
@php-wasm/web	Fornece loadWebRuntime(version) e auxiliares de runtime, rede, armazenamento e workers específicos do navegador.
@php-wasm/node-X-Y e @php-wasm/web-X-Y	Contêm os binários e carregadores WebAssembly para uma versão secundária do PHP, além de artefatos de extensões compatíveis com a versão, quando disponíveis.

Um aplicativo cria o objeto PHP de @php-wasm/universal. O adaptador Node.js ou web configura o ambiente, seleciona uma versão do PHP e importa o pacote da versão correspondente. Por exemplo, loadNodeRuntime('8.4') seleciona @php-wasm/node-8-4.

A API usa versões com ponto, como 8.4, enquanto os nomes de pacotes no npm usam um sufixo com hífen, como 8-4.

Carregadores de plataforma convenientes

Use um adaptador de plataforma quando precisar das integrações de runtime ou quando quiser selecionar versões diferentes do PHP durante a execução. 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'));

Em um navegador, use @php-wasm/web e loadWebRuntime('8.4').

Os adaptadores de plataforma podem encaminhar para todas as versões compatíveis do PHP, e o grafo de dependências publicado inclui os pacotes das versões correspondentes. Isso é conveniente, mas não resulta na menor instalação quando um aplicativo precisa de apenas uma versão do PHP.

Carregue uma versão do PHP diretamente

Para obter o menor conjunto de dependências, omita o adaptador de plataforma e instale @php-wasm/universal com um pacote específico por versão:

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

Esses pacotes são publicados juntos. Mantenha alinhadas as versões de lançamento no npm.

Depois, carregue o módulo compilado pela API de baixo nível:

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 uma build de navegador, use o pacote correspondente, como @php-wasm/web-8-4, com o mesmo fluxo de getPHPLoaderModule() e loadPHPRuntime(). Configure o bundler do navegador para emitir os arquivos .wasm e .so importados como recursos, conforme descrito nas orientações de bundler do @php-wasm/web. Adapte as referências de pacote nessa configuração para o nome específico da versão. Por exemplo, exclua @php-wasm/web-8-4 em vez de @php-wasm/web.

Aqui, um conjunto menor significa instalar uma versão secundária do PHP em vez da matriz completa de versões compatíveis. Cada pacote de versão ainda inclui as variantes compiladas e os artefatos compatíveis necessários para essa versão do PHP.

Essa abordagem direta é intencionalmente de baixo nível. Ela ignora a configuração feita por loadNodeRuntime() ou loadWebRuntime(), incluindo a rede da plataforma, o bloqueio de arquivos do Node.js, o carregamento de extensões e outras integrações específicas do ambiente. Use-a quando a API compartilhada PHP e o sistema de arquivos em memória forem suficientes ou quando seu aplicativo fornecer a configuração necessária do Emscripten.

Veja as versões compatíveis do PHP para escolher o sufixo de pacote correspondente.

Qual abordagem escolher?

• Use @php-wasm/node ou @php-wasm/web para ter configuração e auxiliares de runtime específicos da plataforma e a API mais simples para selecionar versões.
• Carregue @php-wasm/node-X-Y ou @php-wasm/web-X-Y diretamente quando o tamanho da instalação for mais importante que as facilidades do adaptador de plataforma.