Crate ext_php_rs

Source
Expand description

§ext-php-rs

Crates.io docs.rs Guide Workflow Status CI Workflow Status Discord

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

§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
}

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

$ cargo install cargo-php
  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.

§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.

§Usage

Check out one of the example projects:

§Contributions

Contributions are very much welcome. I am a novice Rust developer and any suggestions are wanted and welcome. Feel free to file issues and PRs through Github.

Contributions welcome include:

  • Documentation expansion (examples in particular!)
  • Safety reviews (especially if you have experience with Rust and the Zend API).
  • Bug fixes and features.
  • Feature requests.

When contributing, please keep in mind the following:

  • Create tests if possible.
  • Update the documentation if necessary.
  • Use conventional commits. We use these to automatically generate changelogs.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Resources

§License

Licensed under either of

at your option.

Modules§

alloc
Functions relating to the Zend Memory Manager, used to allocate request-bound memory.
args
Builder and objects relating to function and method arguments.
binary
Provides implementations for converting to and from Zend binary strings, commonly returned from functions such as pack and unpack.
binary_slice
Provides implementations for converting from Zend binary strings as slices, commonly returned from functions such as pack and unpack.
boxed
A pointer type for heap allocation using the Zend memory manager.
builders
Structures that are used to construct other, more complicated types. Generally zero-cost abstractions.
class
Types and traits used for registering classes with PHP.
closureclosure
Types and functions used for exporting Rust closures to PHP.
constant
Types and traits for registering constants in PHP.
convert
Traits used to convert between Zend/PHP and Rust types.
describe
Types used to describe downstream extensions. Used by the cargo-php CLI application to generate PHP stub files used by IDEs.
error
Error and result types returned from the library functions.
exception
Types and functions used for throwing exceptions from Rust to PHP.
ffi
Raw FFI bindings to the Zend API.
flags
Flags and enums used in PHP and the Zend engine.
macros
Macros for interacting with PHP, mainly when the function takes variadic arguments. Unfortunately, this is the best way to handle these. Note that most of these will introduce unsafe into your code base.
prelude
A module typically glob-imported containing the typically required macros and imports.
props
Types and traits for adding properties to PHP classes registered from Rust.
rc
Traits and types for interacting with reference counted PHP types.
types
Types defined by the Zend engine used in PHP.
zend
Types used to interact with the Zend engine.

Macros§

call_user_func
Attempts to call a given PHP callable.
class_derives
Implements a set of traits required to convert types that implement RegisteredClass to and from ZendObjects and Zvals. Generally, this macro should not be called directly, as it is called on any type that uses the php_class macro.
info_table_end
Ends the PHP extension information table. Must be run after all rows have been inserted into the table.
info_table_header
Sets the header for the PHP extension information table. Takes as many string arguments as required.
info_table_row
Adds a row to the PHP extension information table. Takes as many string arguments as required.
info_table_start
Starts the PHP extension information table displayed when running phpinfo(); Must be run before rows are inserted into the table.
parse_args
Parses a given list of arguments using the ArgParser class.
php_print
Prints to the PHP standard output, without a newline.
php_println
Prints to the PHP standard output, with a newline.
throw
Throws an exception and returns from the current function.
zend_fastcall
Defines an extern function with the Zend fastcall convention based on operating system.

Constants§

PHP_DEBUG
Whether the extension is compiled for PHP debug mode.
PHP_ZTS
Whether the extension is compiled for PHP thread-safe mode.
VERSION
ext-php-rs version.

Attribute Macros§

php_class
Annotates a struct that will be exported to PHP as a class.
php_const
Attribute used to annotate constants to be exported to PHP.
php_extern
Attribute used to annotate extern blocks which are deemed as PHP functions.
php_function
Attribute used to annotate a function as a PHP function.
php_impl
Annotates a structs impl block, declaring that all methods and constants declared inside the impl block will be declared as PHP methods and constants.
php_module
Annotates a function that will be used by PHP to retrieve information about the module.
php_startup
Annotates a function that will be called by PHP when the module starts up. Generally used to register classes and constants.

Derive Macros§

ZvalConvert
Derives the traits required to convert a struct or enum to and from a Zval. Both FromZval and IntoZval are implemented on types which use this macro.