ext-php-rs

Bindings and abstractions for the Zend API to build PHP extensions natively in Rust.

• Documentation: https://docs.rs/ext-php-rs
• Guide: https://ext-php.rs

Example

Export a simple function function hello_world(string $name): string to PHP:

#![cfg_attr(windows, feature(abi_vectorcall))]

use ext_php_rs::prelude::*;

/// Gives you a nice greeting!
///
/// @param string $name Your name.
///
/// @return string Nice greeting!
#[php_function]
pub fn hello_world(name: String) -> String {
    format!("Hello, {}!", name)
}

// Required to register the extension with PHP.
#[php_module]
pub fn module(module: ModuleBuilder) -> ModuleBuilder {
    module.function(wrap_function!(hello_world))
}

Use cargo-php to build IDE stubs and install the extension:

$ cargo install cargo-php --locked
  Installing cargo-php v0.1.0
$ cargo php stubs --stdout
  Compiling example-ext v0.1.0
  Finished dev [unoptimized + debuginfo] target(s) in 3.57s
<?php

// Stubs for example-ext

/**
 * Gives you a nice greeting!
 *
 * @param string $name Your name.
 *
 * @return string Nice greeting!
 */
function hello_world(string $name): string {}
$ cargo php install --release
  Compiling example-ext v0.1.0
  Finished release [optimized] target(s) in 1.68s
Are you sure you want to install the extension `example-ext`? yes
$ php -m
[PHP Modules]
// ...
example-ext
// ...

Calling the function from PHP:

var_dump(hello_world("David")); // string(13) "Hello, David!"

For more examples read the library guide.

Features

• Easy to use: The built-in macros can abstract away the need to interact with the Zend API, such as Rust-type function parameter abstracting away interacting with Zend values.
• Lightweight: You don't have to use the built-in helper macros. It's possible to write your own glue code around your own functions.
• Extensible: Implement IntoZval and FromZval for your own custom types, allowing the type to be used as function parameters and return types.

Goals

Our main goal is to make extension development easier.

• Writing extensions in C can be tedious, and with the Zend APIs limited documentation can be intimidating.
• Rust's modern language features and feature-full standard library are big improvements on C.
• Abstracting away the raw Zend APIs allows extensions to be developed faster and with more confidence.
• Abstractions also allow us to support future (and potentially past) versions of PHP without significant changes to extension code.

Documentation

The library guide can be read here.

The project is documented in-line, so viewing the cargo documentation is the best resource at the moment. This can be viewed at docs.rs.

Requirements

• Linux, macOS or Windows-based operating system.
• PHP 8.1 or later.
  • No support is planned for earlier versions of PHP.
  • PHP versions, that no longer receive security updates, will no longer be supported. They might still work, but no guarantees are made.
  • See https://www.php.net/supported-versions.php for information on PHP supported versions and their end of life dates.
• Rust.
  • Currently, we maintain no guarantee of a MSRV, however lib.rs suggests Rust 1.57 at the time of writing.
• Clang 5.0 or later.

Alpine Linux (musl)

Building on Alpine Linux (musl libc) is supported thanks to the runtime feature flag.

# Install dependencies and cargo-php
apk add clang16-libclang
cargo install cargo-php

When building your own extensions, add to your project's .cargo/config.toml:

[target.'cfg(target_env = "musl")']
rustflags = ["-C", "target-feature=-crt-static"]

For static linking, see: https://github.com/KyleMayes/clang-sys#static

Windows Requirements

• Extensions can only be compiled for PHP installations sourced from https://windows.php.net. Support is planned for other installations eventually.
• Rust nightly is required for Windows. This is due to the vectorcall calling convention being used by some PHP functions on Windows, which is only available as a nightly unstable feature in Rust.
• It is suggested to use the rust-lld linker to link your extension. The MSVC linker (link.exe) is supported however you may run into issues if the linker version is not supported by your PHP installation. You can use the rust-lld linker by creating a .cargo\config.toml file with the following content:

  # Replace target triple if you have a different architecture than x86_64
  [target.x86_64-pc-windows-msvc]
  linker = "rust-lld"
  

• The cc crate requires cl.exe to be present on your system. This is usually bundled with Microsoft Visual Studio.
• cargo-php's stub generation feature does not work on Windows. Rewriting this functionality to be cross-platform is on the roadmap.
• To build the application in DEBUG mode on Windows, you must have a PHP SDK built with the DEBUG option enabled and specify the PHP_LIB to the folder containing the lib files. For example: set PHP_LIB=C:\php-sdk\php-dev\vc16\x64\php-8.3.13-src\x64\Debug_TS.

Cargo Features

All features are disabled by default.

• closure - Enables the ability to return Rust closures to PHP. Creates a new class type, RustClosure.
• anyhow - Implements Into<PhpException> for anyhow::Error, allowing you to return anyhow results from PHP functions. Supports anyhow v1.x.
• static - Allows building the library against statically linked clang, for example with static-php-cli

Usage

Check out the awesome-ext-php-rs list for projects built with ext-php-rs.

Contributions

We welcome contributions to the project! Please see the CONTRIBUTING.md file for more information on how to contribute.

Development

allowed_bindings.rs

This file contains the list of allowed bindings for the Zend API. It is acting as a whitelist for the bindings that can be used in the library.

When updating this file you need to also update the docsrs_bindings.rs file. To do this, run the following command from the root of the project:

tools/update_bindings.sh

This will build the bindings using docker, and then copy the docsrs_bindings.rs file to the root of the repository. This will ensure that the file is always built in the same environment.

Docker and buildx are required to run the script, so make sure you have those installed.

Resources

• PHP Internals Book

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE_APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE_MIT or http://opensource.org/licenses/MIT)

at your option.