ext-php-rs

The ext-php-rs crate provides a suite of procedural macros used to annotate Rust types and functions so they can be exported to PHP. These macros allow you to define PHP modules, startup functions, classes, and functions without manually manipulating PHP zvals.

Key macros include:

• #[php_module]: Defines the entry point function PHP uses to retrieve your extension.
• #[php_startup]: Defines the initialization function called when the extension starts.
• #[php_function]: Exports a Rust function as a PHP function.
• #[php_class]: Exports a Rust struct or enum as a PHP class.
• #[php_impl]: Exports a Rust impl block, including its methods and constants, to PHP.
• #[php_const]: Exports a Rust constant as a global PHP constant.
• #[php_interface]: Exports a Rust trait as a PHP interface.
• #[php_extern]: Annotates extern blocks containing PHP functions.
• #[php]: A generic attribute used to modify the default behavior of most other macros.

In ext-php-rs, binary data (typically generated via PHP's pack or unpack functions) is represented as a string in PHP. You can use BinarySlice<T> in Rust to treat these PHP strings as read-only slices of type T without copying the underlying data.

Requirements

To use BinarySlice<T>, the type T must implement the PackSlice trait. This is currently implemented for most primitive numbers:

• Signed integers: i8, i16, i32, i64, isize
• Unsigned integers: u8, u16, u32, u64, usize
• Floats: f32, f64

Mapping Table

Implementation Detail

The data is converted into a slice, and the pointer to the data is set as the string pointer, with the length of the array being the length of the string.

#![cfg_attr(windows, feature(abi_vectorcall))]
extern crate ext_php_rs;
use ext_php_rs::prelude::*;
use ext_php_rs::binary_slice::BinarySlice;

#[php_function]
pub fn test_binary_slice(input: BinarySlice<u8>) -> u8 {
    let mut sum = 0;
    for i in input.iter() {
        sum += i;
    }

    sum
}

fn main() {}

When writing PHP functions in Rust, you must decide how to handle variable ownership and mutation. Using &mut Zval directly is considered legacy and forces PHP callers to use pass-by-reference syntax (&$x), which prevents passing literals (e.g., foo([1,2,3])).

To decouple Rust mutability from PHP's pass-by-reference semantics, use Separated or PhpRef:

| Type | PHP syntax | Modifies caller? | Use case |
|---|---|---|---|
| `Separated` | `foo($x)` or `foo([1,2])` | No | Mutate a local copy (COW) |
| `PhpRef` | `foo(&$x)` | Yes | Modify the caller's variable |
| `&Zval` | `foo($x)` | No | Read-only access |
| `&mut Zval` | `foo(&$x)` | Yes | Legacy — prefer `PhpRef` |

When PHP triggers a 'bailout' (via exit(), die(), or a fatal error), it uses longjmp to unwind the stack. This bypasses Rust's normal drop semantics, meaning destructors for stack-allocated values will not run, potentially causing resource leaks (e.g., file handles, network connections, or locks).

You can prevent these leaks using two primary methods:

1. try_call: Use this for PHP callbacks. It catches bailouts internally and returns a Result, allowing the Rust function to return normally and trigger standard destructors.
2. BailoutGuard: Use this for critical resources that must be cleaned up even if a bailout occurs directly (not through a try_call catch).

#[php_function]
pub fn process_file(callback: ZendCallable) {
    let file = File::open("data.txt").unwrap();

    // If callback calls exit(), the file handle leaks!
    callback.try_call(vec![]);

    // file.drop() never runs
}