Php-Wasm Methods

constructor

The concrete php-wasm classes all extend the same base runtime API:

  • PhpWeb
  • PhpWorker
  • PhpWebview
  • PhpNode

They accept the same core options bucket, with different defaults for binary loading and filesystem persistence depending on environment.

Common constructor options

version

string

Selects the PHP runtime version to load. Defaults to 8.4. PhpNode instead uses the PHP_VERSION environment variable when it names a supported version (8.0–8.5).

const php = new PhpWeb({version: '8.4'});

SDL runtime selection

Install php-sdl-wasm and choose a versioned entry for SDL graphics, input and audio. The ordinary php-wasm package stays independent of that build. The previous variant: '_sdl' option is no longer supported.

import {PhpSdl} from 'php-sdl-wasm/php8.4-sdl.mjs';

const php = new PhpSdl({canvas: document.querySelector('canvas')});

Create the canvas first. See SDL and OpenGL for the package, build options and example controls.

canvas

HTMLCanvasElement

Pass the canvas used by an SDL-enabled browser runtime. The cube example needs WebGL2 and a focusable canvas (tabindex="0") for keyboard input. Pass a fresh canvas when replacing the runtime or switching graphics context types.

sharedLibs

array of strings or objects

Loads shared extensions before boot and writes extension=... lines for any item with ini: true.

const php = new PhpWeb({
  sharedLibs: [
    { url: 'https://unpkg.com/php-wasm-sqlite/php8.4-sqlite.so', ini: true },
    { url: 'https://unpkg.com/php-wasm-sqlite/libsqlite3.so', ini: false },
  ]
});

ESM helper packages can be passed directly here. CommonJS callers should pass strings, URLs, or {name, url, ini} records manually instead.

dynamicLibs

array of strings or objects

Resolved the same way as sharedLibs, but never written into php.ini.

The same CommonJS rule applies here: pass manual strings, URLs, or objects rather than the ESM helper packages.

files

array of objects

Preloads arbitrary files into the runtime before startup.

Dynamic and shared intl builds use this mechanism to provide icudt72l.dat under /preload. Static intl builds can bundle the same file into the runtime .data package instead.

const php = new PhpWeb({
  files: [
    {
      name: 'icudt72l.dat',
      parent: '/preload/',
      url: 'https://unpkg.com/php-wasm-intl/icudt72l.dat'
    }
  ]
});

locateFile

function(path, directory): string | URL | undefined

Overrides how .wasm, shared libraries, preload assets, and other runtime files are resolved.

ini

string

Additional php.ini lines appended to the generated runtime config.

const php = new PhpWeb({ini: `
display_errors=1
memory_limit=256M
`});

persist

object or array

Mounts persistent filesystems. In web runtimes this is typically IDBFS, and in PhpNode it can point to a host directory.

autoTransaction

boolean

Defaults to true. Controls whether queued operations automatically start and commit filesystem transactions.

shared

object

Shared JS object registry used internally by php.x and php.r when VRZNO is enabled. You generally do not need to set this manually.

php.run

Run a PHP script and return its numeric exit code. php.run() is the right choice when you want script semantics, output on STDOUT/STDERR, or mixed PHP/HTML.

The examples in this project use an opening <?php tag, and that remains the safest form to document and copy.

You’ll need to use event listeners to capture output.

const exitCode = await php.run(`<?php
    $time = strtotime('8:00pm 2 days ago');
    $date = date('Y-m-d H:i:s', $time);
    echo $date;`
);

php.exec

Execute a single PHP expression and return the result as a string.

Unlike php.run(), this should:

  • not start with <?php
  • not end in a semicolon
  • evaluate to one expression

Multiple steps can be wrapped in an IIFE.

If you want automatic JS marshalling for functions, arrays, objects, or other VRZNO-backed values, use php.x instead.

To run multiple commands in a single statement, use an IIFE.

const date = await php.exec(`(function() {
    $time = strtotime('8:00pm 2 days ago');
    $date = date('Y-m-d H:i:s', $time);
    return $date;
})();`);

php.r

Tagged template function companion to php.run(). If Vrzno is enabled, allows rich JS values to be interpolated into PHP code.

Just like php.run(), this will return a non-zero value in case of error.

const exitCode = await php.r`<?php
    $time = strtotime('8:00pm 2 days ago');
    $date = date('Y-m-d H:i:s', $time);
    echo $date;`;

php.x

Tagged template function companion to php.exec(). If Vrzno is enabled, allows rich JS values to be interpolated into PHP code.

Like php.exec(), this may only evaluate a single expression at a time. Unlike php.exec(), it will marshal the result back into Javascript when VRZNO support is available.

const callback = await php.x`function() {
    return 321;
}`;

const value = callback();

php.refresh

Refreshes the PHP runtime and clears in-memory state. Any JS handles backed by live PHP values become invalid after a refresh.

await php.refresh();

Input and Filesystem Helpers

All PhpBase implementations also expose the queued helper methods below:

  • php.inputString(string)
  • php.input(bytes)
  • php.analyzePath(path)
  • php.readdir(path, options?)
  • php.readFile(path, options)
  • php.stat(path)
  • php.mkdir(path)
  • php.rmdir(path)
  • php.rename(path, newPath)
  • php.writeFile(path, data, options)
  • php.unlink(path)

These methods run through the same queueing and transaction logic as run, exec, r, and x.

readdir returns string[] by default. With {withFileTypes: true}, it returns Array<{name: string, isFolder: boolean}>. Both forms include . and ..; classification follows links and metadata errors reject the call. See Filesystem Operations and Transactions for persistence behavior.