HomeRésuméOpen SourceWorkBlog
    Table of contents
  1. (top)
  2. ParseCallbacks
    1. AnonymousTypeNames
    2. BuildIdCallbacks
    3. CommentProcessor
    4. ExplicitIntTypesCallbacks
    5. IntTypeCastCallbacks
  3. ZendHeaderIterator
  4. PhpConfigRunner
  5. Macros

RSPHP Part 2: Build Tools

Friday, 20 November 2026

In my last post, I talked about the rsphp-sys crate, which provides Rust bindings for PHP's C ABI for building PHP extensions in Rust. As I mentioned, I fully expect extension developers to override the definition of the rsphp-sys crate to customize their bindings. In order to facilitate those overrides, most of the build logic comes from a separate crate, rsphp-build-tools.

The latest version of the build tools crate, version 0.1.3 (documentation), provides seven different utilities for use in the rsphp-sys build script. Five are structs that implement bindgen's ParseCallbacks trait, one is a tool for iterating over PHP's C header files, and the seventh is a utility for running the php-config command.

References to PHP use the latest stable release as of writing (PHP 8.6.0), likewise with Rust (Rust 1.100.0).

ParseCallbacks

There are two primary methods to override bindgen's default behavior or add configuration. The first is calling the various methods on the Builder instance to set options directly, like which files should be parsed and what types/functions/variables/etc. should have bindings generated. The second is by using the parse_callbacks() method to add sets of callbacks (objects implementing the ParseCallbacks trait) to the builder. By putting as much logic as possible in those callbacks, the build script just needs to add the callbacks to the builder.

The five ParseCallbacks-implementing types that the build tools crate provides are:

AnonymousTypeNames

The AnonymousTypeNames struct renames some types generated by bindgen to slightly clearer names. PHP's C ABI includes a number of anonymous structs and unions which need to be named to represent them in Rust.

Bindgen generates names like _zend_function__bindgen_ty_1 or _zval_struct__bindgen_ty_1__bindgen_ty_1__bindgen_ty_1. Each anonymous type gets a __bindgen_ty_{counter} suffix appended to the name of its containing type, which results in unhelpful and, in the case of nested anonymous types, long and unwieldy names. The AnonymousTypeNames struct adjusts some of the auto-generated names to be a bit clearer, e.g. _zend_function__common and _zval_u1_v_u for those two.

BuildIdCallbacks

The BuildIdCallbacks struct is used to replace the definition of the ZEND_MODULE_BUILD_ID C macro with one that bindgen can understand. That macro, split here over multiple lines for readability, is defined as:

#define ZEND_MODULE_BUILD_ID "API" ZEND_TOSTR(ZEND_MODULE_API_NO) ZEND_BUILD_TS \
	ZEND_BUILD_DEBUG ZEND_BUILD_SYSTEM ZEND_BUILD_EXTRA

and draws on definitions from zend_build.h

#define ZEND_TOSTR_(x) #x
#define ZEND_TOSTR(x) ZEND_TOSTR_(x)

#ifdef ZTS
#define ZEND_BUILD_TS ",TS"
#else
#define ZEND_BUILD_TS ",NTS"
#endif

#if ZEND_DEBUG
#define ZEND_BUILD_DEBUG ",debug"
#else
#define ZEND_BUILD_DEBUG
#endif

#if defined(ZEND_WIN32) && defined(PHP_COMPILER_ID)
#define ZEND_BUILD_SYSTEM "," PHP_COMPILER_ID
#else
#define ZEND_BUILD_SYSTEM
#endif

/* for private applications */
#define ZEND_BUILD_EXTRA

The ZEND_TOSTR macro makes use of C's "stringizing" operator to convert the value of the argument (here the value of the ZEND_MODULE_API_NO macro) into a string literal. After substituting the parts of the build ID, the definition might look something like the following (for a debug, NTS build on PHP 8.6)

#define ZEND_MODULE_BUILD_ID "API" "20261112" ",NTS" ",debug"

At that point, the macro definition takes advantage of the fact that C concatenates adjacent string literals into a single string to result in the overall build ID, in this case "API20261112,NTS,debug".

The combination of the ZEND_TOSTR macro and the concatenation of the different parts of the build ID mean that the ZEND_MODULE_BUILD_ID definition cannot be generated by bindgen's default handling.

For other constants, I would probably just say "oh well" and move on, but the build ID is part of the module definition of PHP extensions. It must be present in the module entry, and must match the ID of the PHP engine, for extensions to be loadable. As a result, I wrote the BuildIdCallbacks type, implementing macro-processing callbacks to read in the definitions of ZEND_MODULE_API_NO, ZEND_BUILD_TS, and ZEND_BUILD_DEBUG and then updating the definition of ZEND_MODULE_BUILD_ID.

CommentProcessor

The CommentProcessor struct is probably not as useful to extension developers, but I figured it was still worth factoring out. All it does is add backticks in the documentation comment of the zend_ini_parse_quantity function declaration (source) so that the indented parts of that comment are treated by rustdoc as plain text. Otherwise

  1. Per the CommonMark spec for markdown the indented lines are treated as a code block (section 4.4).
  2. Since it is missing a declared language, rustdoc treats it as a Rust code block (documentation).
  3. The documentation, since it is not valid Rust code, triggers the invalid_rust_codeblocks lint.

Since I use these build tools for the version of rsphp-sys that is documented on docs.rs, I want the zend_ini_parse_quantity() documentation to treat the indented parts of the comment as text - see the result. It isn't perfect, as shown by one of the bullet points having the second line be treated as a code block, but at least it avoids the warnings from rustdoc.

Others probably aren't going to be generating the documentation for their overridden rsphp-sys dependency, in which case they are free to skip using the CommentProcessor.

ExplicitIntTypesCallbacks

The ExplicitIntTypesCallbacks struct is used to force some of the Rust integer constants corresponding to C preprocessor constants to have specific types. I mentioned this briefly in my last post - by default, bindgen will store the values in 32-bit types (i32 or u32), which prompts Rust to complain when trying to use the values in places expecting other types.

The list of constants is currently manually curated, based on errors I encounter when writing extensions in Rust and investigating how the corresponding constants are used in C. For example, MODULE_DEP_REQUIRED, MODULE_DEP_CONFLICTS, and MODULE_DEP_OPTIONAL are defined as one, two, and three respectively. They could use any of Rust's integer types to represent the values. However, they are stored in the type field of the _zend_module_dep struct, which is a unsigned char in C. Thus, the callbacks instruct bindgen to use the equivalent Rust type, c_uchar.

IntTypeCastCallbacks

The IntTypeCastCallbacks struct is used to handle integer casts in C that bindgen cannot handle. For example, the HT_INVALID_IDX preprocessor constant is defined in the C code as

#define HT_INVALID_IDX ((uint32_t) -1)

Obviously, a negative value cannot be stored in an unsigned integer. Thus, the value wraps around, and becomes the maximum unsigned value for a 32-bit integer, 2^32 - 1 (4294967295). Since bindgen does not handle that wrapping, the IntTypeCastCallbacks struct does it instead, replacing the macro definition with the resulting value and also telling bindgen what integer type to use for the resulting constant. Currently, the utility handles uint32_t and uint16_t casts in the C code, but it can be expanded to others if needed, e.g. some other C preprocessor macros in PHP use size_t or unsigned int.

ZendHeaderIterator

The ZendHeaderIterator provides an iterator over the C header files in PHP's Zend/ directory that bindings should be generated for. While bindgen can be instructed to include all headers in a given directory, a number of the header files in that directory are internal and don't have anything useful to process, e.g. the definition of the Zend virtual machine (zend_vm_def.h, currently over 10k lines of code) or the resulting generated zend_vm_execute.h, which is currently over 120k lines of code. I'm not sure how quickly bindgen would process these files, or even if it could, since at least the definition file isn't actually valid C code. Either way, bindings for them are not needed, so having a list of allowed header files makes it easy to avoid them.

PhpConfigRunner

The PhpConfigRunner utility is new in version 0.1.3 of the rsphp crates. It serves to deduplicate calls to php-config shell script, used for locating PHP's include directory (needed to locate the header files to process) and the additional headers that PHP depends on.

Different systems can have PHP installed in different places, and without the php-config script building the FFI bindings would require manually locating all of PHP header files. Plus, depending on how PHP is built it might depend on different sets of external system headers. I thus expect that all overrides of the rsphp-sys crate will want to use php-config for identifying dependencies, and this wrapper should make things slightly easier.

Macros

We've discussed the rsphp-sys crate, which provides bindings for PHP's C ABI, and the rsphp-build-tools crate, which simplifies building those bindings, but that isn't the end of the story. I've heard it said that PHP isn't really written in C, but rather in a macro language built on top of C, and to some extent, that is true. PHP uses macros everywhere, and without corresponding Rust macros, extension development would be a lot harder. In my next post, I'll dive into the rsphp-macros-c crate, which provides some Rust macros to match the C ones.

Tags: