Static Linking into php-src
Extensions built with ext-php-rs are normally compiled as a cdylib and
loaded at runtime with an extension= ini line. PHP also supports compiling
extensions directly into the php binary. This is how fully static PHP
builds work, for example FrankenPHP static binaries
built with static-php-cli:
there is no .so and no ini line, the extension is part of the binary.
This page describes how to build an ext-php-rs extension as a static library
and link it into php-src. Note that this is an advanced use-case; if in doubt
prefer loading your extension(s) dynamically and make sure to read the
Caveats section below if you go the static route.
How php-src registers builtin extensions
Every builtin extension lives in php-src/ext/<name>/ with a config.m4.
During ./buildconf, php-src scans the headers of enabled extensions for the
token phpext_ and collects phpext_<name>_ptr pointers into the
php_builtin_extensions[] array in main/internal_functions.c. That array
is registered during php_module_startup().
The array needs a link-time-constant address, conventionally
&<name>_module_entry. An ext-php-rs extension builds its
zend_module_entry at runtime inside get_module(), so a small C shim
bridges the two: it defines the <name>_module_entry symbol and fills it
from the crate-prefixed <crate_name>_get_module() export in a constructor,
which runs before php_module_startup().
Crate setup
Add staticlib to your crate type, keeping cdylib for regular builds:
[lib]
crate-type = ["staticlib", "cdylib"]
Static builds must be compiled with EXT_PHP_RS_STATIC_EXT=1:
EXT_PHP_RS_STATIC_EXT=1 cargo build --release
The variable does two things. It removes the unmangled get_module export
(the crate-prefixed <crate_name>_get_module remains), so the binary can also
contain C extensions that export get_module, for example ones missing the
#ifdef COMPILE_DL_<EXT> guard around ZEND_GET_MODULE. It also defines
ZEND_ENABLE_STATIC_TSRMLS_CACHE, which makes the extension read the main
binary’s _tsrm_ls_cache thread-local directly instead of calling
tsrm_get_ls_cache() on every globals access; php-src compiles all builtin
extensions this way. The TSRMLS part only matters on ZTS targets and is
harmless on NTS. Dynamic builds (extension= / dl()) must not set the
variable, since PHP resolves the unprefixed get_module symbol.
Note that a static library built in this mode can only be linked into a PHP
binary. It cannot be loaded with extension= or linked against a prebuilt
libphp, because _tsrm_ls_cache only resolves inside php-src itself.
Generating the glue
The cargo-php CLI generates the three
files php-src needs:
cargo php static-glue
This writes a directory named after your extension containing:
config.m4: enables the extension with--enable-<name>and links the prebuiltlib<name>.a.php_<name>.h: declares<name>_module_entryand thephpext_<name>_ptrdefine that php-src scans for.<name>_glue.c: the constructor shim copying*<crate_name>_get_module()into<name>_module_entry.
The extension name defaults to the library target name with dashes replaced
by underscores; override it with --ext-name. The override only affects file
and configure naming; the Rust symbols come from the library target name;
override it with --lib-name if cargo metadata is not available.
The two-pass build
Building the Rust library requires php-config and the PHP headers, which do
not exist yet when you are building the very PHP you want to link into. The
solution is two passes:
-
Build (or install) a PHP with the exact same version, ZTS mode and debug mode as your final binary. Only its
php-configand headers are needed.cd php-src ./buildconf ./configure --enable-zts --disable-all --enable-cli --prefix=$HOME/php-pass1 make -j$(nproc) && make install -
Build the Rust static library against pass 1:
PHP_CONFIG=$HOME/php-pass1/bin/php-config \ EXT_PHP_RS_STATIC_EXT=1 \ cargo build --release -
Copy the glue and the static library into php-src:
cargo php static-glue cp -r my_ext php-src/ext/my_ext cp target/release/libmy_ext.a php-src/ext/my_ext/ -
Build the final PHP:
cd php-src ./buildconf --force ./configure --enable-zts --enable-my_ext <other flags> make -j$(nproc)Alternatively,
./config.nice --enable-my_extrerunsconfigurewith the flags of the previous invocation plus the new one. -
Verify:
sapi/cli/php -m | grep my_ext sapi/cli/php -r 'var_dump(my_function());'
The module is listed without any extension= ini line. Note that php -m
prints the module name from your crate’s Cargo.toml package name, which can
differ from the C extension name when the package name contains dashes.
For FrankenPHP and static-php-cli the integration point is identical: drop
the glue directory and the .a into the php-src tree those tools build from
and add --enable-<name> to the configure flags.
Caveats
- One Rust extension per PHP binary. The
ext_php_rs_*symbols have fixed names, and two Rust static libraries collide on the Rust standard library symbols. Bundle all your Rust functionality into a single extension crate. Co-linking with C extensions is fine, including ones that export an unguardedget_module, as long as the Rust library is built withEXT_PHP_RS_STATIC_EXT=1. - gcc/clang only. The shim relies on
__attribute__((constructor)). Statically linking into a Windows PHP build is not supported. - Keep the
.ain sync. The static library embeds bindings generated from the pass-1 PHP headers. Rebuild it whenever the target PHP version changes. --enable-<name>=sharedis rejected by the generatedconfig.m4: for shared builds, use the regularcdylibworkflow instead.