.php-wasm-rc

The .php-wasm-rc file is a configuration file that allows you to specify custom build options for php-wasm. When placed in the same directory as your project, the php-wasm-builder tool will use it to customize the build process.

Example .php-wasm-rc file:

# Select a PHP version
PHP_VERSION=8.4

# Build the package to a directory other than the current one (RELATIVE path)
PHP_DIST_DIR=./public

# Build the extensions to a directory other than the current one (RELATIVE path)
PHP_ASSET_DIR=./public


# Build the cgi package to a directory other than the current one (RELATIVE path)
PHP_CGI_DIST_DIR=./public

# Build the cgi package's extensions to a directory other than the current one (RELATIVE path)
PHP_CGI_ASSET_DIR=./public

# Build the cli package and its extensions to relative output directories
PHP_CLI_DIST_DIR=./public
PHP_CLI_ASSET_DIR=./public

# Build the phpdbg package and its extensions to relative output directories
PHP_DBG_DIST_DIR=./public
PHP_DBG_ASSET_DIR=./public

# Space separated list of files/directories to include under /preload.
# Relative paths are resolved from the current project directory.
PRELOAD_ASSETS=./php-scripts ~/other-dir/example.php

# Memory to start the instance with, before growth
INITIAL_MEMORY=2048MB

# Build with assertions enabled
ASSERTIONS=0

# Select the optimization level
OPTIMIZE=3

# Build with extensions
WITH_GD=1
WITH_LIBPNG=1
WITH_LIBJPEG=1
WITH_FREETYPE=1

Options

The following options may appear in .php-wasm-rc.

PRELOAD_ASSETS

Use the PRELOAD_ASSETS key in your .php-wasm-rc file to define a list of files and directories to include by default.

The files and directories will be collected into a single directory. Individual files & directories will appear in the top level, while directories will maintain their internal structure.

When you use php-wasm-builder, relative entries are resolved from the current project directory. Anchored paths such as /path/to/file.txt and ~/path/to/file.txt are left unprefixed so the shell can resolve them normally.

PRELOAD_ASSETS is a whitespace-delimited Make variable. Paths containing spaces are not supported.

These files & directories will be available under /preload in the final package, packaged into the .data file that is built along with the .wasm file.

PRELOAD_ASSETS='./php-scripts /some/directory ~/other-dir/example.php /path/to/other_file.txt'

PHP_VERSION

8.0|8.1|8.2|8.3|8.4|8.5

PHP 8.0 builds must also set WITH_PDO_PGLITE=0, because PDO-PGlite requires PHP 8.1 or newer.

PHP_DIST_DIR

This is the directory where javascript & wasm files will be built to, relative to the current directory.

PHP_ASSET_DIR

This is the directory where shared libs, extension, .data files & other supporting files will be built to, relative to the current directory. Defaults to PHP_DIST_DIR.

OPTIMIZE

0|1|2|3

The optimization level to use while compiling.

SUBOPTIMIZE

The optimization level to use while compiling libraries. Defaults to OPTIMIZE.

ASSERTIONS

0|1

Build with/without assertions.

Extension Flags

Extensions may be compiled as dynamic, shared, or static.

dynamic - these extensions may be loaded selectively at runtime.
shared - these extensions will always be loaded at startup and can be cached and reused.
static - these extensions will be built directly into the main wasm binary (may cause a huge filesize).

(defaults provided below in bold)

The following options are available for building static PHP extensions:

WITH_BCMATH    # [0, 1] Enabled by default
WITH_CALENDAR  # [0, 1] Enabled by default
WITH_CTYPE     # [0, 1] Enabled by default
WITH_EXIF      # [0, 1] Enabled by default
WITH_FILTER    # [0, 1] Enabled by default
WITH_TOKENIZER # [0, 1] Enabled by default
WITH_VRZNO     # [0, 1] Enabled by default

The following extension may be compiled as static, shared or dynamic:

WITH_PHAR      # [0, 1, static, dynamic]
WITH_LIBXML    # [0, 1, static, shared, dynamic]
WITH_ICONV     # [0, 1, static, shared, dynamic]
WITH_SQLITE    # [0, 1, static, shared, dynamic]

WITH_LIBZIP    # [0, 1, static, shared, dynamic]
WITH_ZLIB      # [0, 1, static, shared, dynamic]

WITH_GD        # [0, 1, static, dynamic]
WITH_LIBPNG    # [0, 1, static, shared]
WITH_FREETYPE  # [0, 1, static, shared]
WITH_LIBJPEG   # [0, 1, static, shared]

WITH_YAML      # [0, 1, static, shared, dynamic]
WITH_TIDY      # [0, 1, static, shared, dynamic]
WITH_MBSTRING  # [0, 1, static, dynamic]
WITH_ONIGURUMA # [0, 1, static, shared, dynamic]
WITH_OPENSSL   # [0, 1, static, shared, dynamic]
WITH_INTL      # [0, 1, static, shared, dynamic]

SDL runtime options

The standalone php-sdl-wasm runtime uses these additional flags:

Option	Values	Default
`WITH_SDL`	`0`, `1`, legacy `dynamic` alias for `1`	`0` normally; enabled by the SDL target
`WITH_SDL_IMAGE`	`0`, `1`	Follows SDL
`WITH_SDL_MIXER`	`0`, `1`	Follows SDL
`WITH_SDL_TTF`	`0`, `1`	Follows SDL
`WITH_OPENGL`	`0`, `1`	Follows SDL

php-wasm-builder build sdl mjs enables SDL and packages the standalone browser runtime. The source checkout uses make sdl-mjs. Both targets set WITH_SDL=1; the _sdl suffix only separates internal native outputs and configure caches. Add-ons require SDL and are compiled into the runtime. SDL_image needs enabled WITH_LIBPNG and WITH_LIBJPEG; SDL_ttf needs WITH_FREETYPE. These reuse the existing static/shared codec libraries. WITH_ZLIB=0 still supplies the native zlib archive when image/font decoding needs it.

To retain only core SDL, set all four add-on flags to 0 in .php-wasm-rc, then run php-wasm-builder build sdl mjs with php-wasm-builder 0.2.0 or later. The output in packages/php-sdl-wasm includes the required native libraries and preload data; keep those files with the runtime.

WITH_PHAR

static|dynamic

When compiled as a dynamic extension, this will produce the extension file php8.x-phar.so.

WITH_LIBXML

static|shared|dynamic

This actual php-libxml extension must be statically compiled, but libxml itself may be loaded as a shared library.

When compiled as a shared library, it will produce the library libxml.so.

WITH_LIBZIP

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-zip.so.

When compiled as a dynamic or shared extension, it will produce the library libzip.so.

This extension depends on zlib.

WITH_ICONV

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-iconv.so.

When compiled as a dynamic or shared extension, it will produce the library libiconv.so.

WITH_SQLITE

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extensions php8.x-sqlite.so, & php8.x-pdo-sqlite.so.

When compiled as a dynamic or shared extension, it will produce the library libsqlite3.so.

WITH_GD

static|dynamic

If WITH_GD is set to dynamic, then libpng, libjpeg, and freetype will load after GD is loaded.

When compiled as a dynamic extension, this will produce the extension php8.x-gd.so.

WITH_LIBPNG

static|shared

When compiled as a shared library, this will produce the library libpng.so.

If WITH_GD is dynamic, then loading will be deferred until after gd is loaded.

WITH_FREETYPE

static|shared

When compiled as a shared library, this will produce the library libfreetype.so.

If WITH_GD is dynamic, then loading will be deferred until after gd is loaded.

WITH_LIBJPEG

static|shared

When compiled as a shared library, this will produce the library libjpeg.so.

If WITH_GD is dynamic, then loading will be deferred until after gd is loaded.

WITH_ZLIB

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-zlib.so.

When compiled as a dynamic or shared extension, it will produce the library libz.so.

WITH_YAML

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-yaml.so.

When compiled as a dynamic or shared extension, it will produce the library libyaml.so.

WITH_TIDY

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-tidy.so.

When compiled as a dynamic or shared extension, it will produce the library libtidy.so.

WITH_MBSTRING

static|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-mbstring.so.

WITH_ONIGURUMA

static|shared|dynamic

Support library for mbstring.

When compiled as a dynamic or shared library, this will produce the library libonig.so.

If WITH_MBSTRING is dynamic, then loading will be deferred until after mbstring is loaded.

WITH_OPENSSL

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-openssl.so.

When compiled as a dynamic or shared extension, it will produce the libraries libssl.so & libcrypto.so.

WITH_INTL

static|shared|dynamic

When compiled as a dynamic extension, this will produce the extension php8.x-intl.so, the following libraries, and the preload file icudt72l.dat:

libicuuc.so
libicutu.so
libicutest.so
libicuio.so
libicui18n.so
libicudata.so
icudt72l.dat

When compiled as a shared extension, the intl extension itself is built into the base runtime. Shared builds still emit the ICU support libraries above and the preload file icudt72l.dat, but they should not reload php8.x-intl.so.

When compiled as a static extension, icudt72l.dat is bundled into the runtime .data payload instead of being loaded separately.