Php-Cgi-Wasm Methods

constructor

The php-cgi-wasm constructor takes an options bucket object as its single parameter. The keys are outlined below.

const php = new PhpCgiWorker();

The concrete classes are:

  • PhpCgiNode
  • PhpCgiWorker

version

string

Selects the PHP-CGI runtime version to load.

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

sharedLibs

array of strings or objects

const php = new PhpCgiWorker({
    sharedLibs: [
        { url: 'https://unpkg.com/php-wasm-sqlite/php8.4-sqlite.so', ini: true  },
        { url: 'https://unpkg.com/php-wasm-sqlite/sqlite.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 like 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

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 PhpCgiWorker({
    files: [
        {
            name: 'icudt72l.dat',
            parent: '/preload/',
            url: 'https://unpkg.com/php-wasm-intl/icudt72l.dat'
        }
    ]
});

actions

object<string, function>

Extra message-bus actions exposed through php.handleMessageEvent. Action handlers receive the PHP wrapper as their first argument.

const php = new PhpCgiWorker({
    actions: {
        helloWorld: (php, name) => {
            return `Hello, ${name}!`;
        },
    }
});

locateFile

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

const php = new PhpCgiWorker({
    locateFile: path => `/assets/php/${path}`
});

docroot

string

Tells php where to find the php source files for your website inside the emscripten filesystem.

const php = new PhpCgiWorker({
    docroot: '/persist/public'
});

entrypoint

string

const php = new PhpCgiWorker({
    entrypoint: 'index.php'
});

prefix

string

If a request is made with a pathname that starts with prefix, php-cgi-wasm will activate and attempt to route the request to PHP rather than allowing it to proceed to the network.

const php = new PhpCgiWorker({
    prefix: '/php-wasm'
});

exclude

array of strings

If a request matched the prefix, but the URL also matches an element of exclude, then PHP will ignore the request and it will be sent to the network.

const php = new PhpCgiWorker({
    exclude: ['/php-wasm/assets', '/php-wasm/static']
});

rewrite

function(string): string | {scriptName: string, path: string}

Pass a function that will receive paths and rewrite them before PHP begins routing.

const php = new PhpCgiWorker({
    rewrite: path => path === '/php-wasm' ? '/php-wasm/index.php' : path
});

types

object.<string, string>

const php = new PhpCgiWorker({
    types: {
        svg: 'image/svg+xml',
        webp: 'image/webp'
    }
});

notFound

function(request): response

This callback will be called when the requested PHP script/static asset is not found, and should return a Response object.

const php = new PhpCgiWorker({
    notFound: request => new Response('404 - Not Found', {status: 404})
});

onRequest

function(request, response): void

Callback to run for every request.

const php = new PhpCgiWorker({
    onRequest: (request, response) => {
        console.log(request.url, response.status);
    }
});

env

object<string, string>

Environment variables to inject into the CGI runtime before each request.

const php = new PhpCgiWorker({
    env: {
        APP_ENV: 'development',
        APP_DEBUG: '1'
    }
});

autoTransaction

boolean

Defaults to true. Controls whether request handling and filesystem operations automatically wrap themselves in filesystem transactions.

maxRequestAge

number

Maximum request age in milliseconds. Older requests return 408.

staticCacheTime

number

How long static-file responses may be cached in browsers with the Cache API available.

dynamicCacheTime

number

Stored setting for dynamic response cache lifetime.

vHosts

array of objects

Mount multiple PHP applications under different path prefixes.

const php = new PhpCgiWorker({
    vHosts: [
        {
            pathPrefix: '/php-wasm/app-a',
            directory: '/persist/app-a/public',
            entrypoint: 'index.php'
        }
    ]
});

handleInstallEvent

In service workers, this hooks into the install event. This should be set up as follows:

self.addEventListener('install', event => php.handleInstallEvent(event));

In service workers, this hooks into the activate event. This should be set up as follows:

handleActivateEvent

self.addEventListener('activate', event => php.handleActivateEvent(event));

In service workers, this hooks into the message event. This should be set up as follows:

handleMessageEvent

self.addEventListener('message', event => php.handleMessageEvent(event));

handleMessageEvent exposes the built-in filesystem and settings methods over the worker message channel:

  • analyzePath
  • readdir
  • readFile
  • stat
  • mkdir
  • rmdir
  • writeFile
  • rename
  • unlink
  • putEnv
  • refresh
  • getSettings
  • setSettings
  • getEnvs
  • setEnvs
  • storeInit

It will also dispatch any custom handlers provided via the actions constructor option.

In service workers, this hooks into the fetch event, and will call the request method in service workers.

This should be set up as follows:

handleFetchEvent

self.addEventListener('fetch', event => php.handleFetchEvent(event));

request

The request method only needs to be called manually if PHP-CGI is running under Node.js or inside a webpage. When running in a service worker, handleFetchEvent will call request internally.

It returns a Response.

refresh

This will discard the current PHP instance and spin up a brand new one.

Filesystem and Settings Helpers

PhpCgiBase also exposes:

  • analyzePath(path)
  • readdir(path)
  • readFile(path, options)
  • stat(path)
  • mkdir(path)
  • rmdir(path)
  • rename(path, newPath)
  • writeFile(path, data, options)
  • unlink(path)
  • putEnv(name, value)
  • getSettings()
  • setSettings(settings)
  • getEnvs()
  • setEnvs(env)
  • storeInit()