Crate ext_php_rs[−][src]
Expand description
ext-php-rs
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:
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
andFromZval
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
- PHP 8.0 or later
- No support is planned for lower versions.
- Linux or Darwin-based OS
- Rust - no idea which version
- Clang 3.9 or greater
See the following links for the dependency crate requirements:
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
- ImplementsInto<PhpException>
foranyhow::Error
, allowing you to return anyhow results from PHP functions. Supports anyhow v1.x.
Usage
This project only works for PHP >= 8.0 (for now). Due to the fact that the PHP extension system relies heavily on C macros (which cannot be exported to Rust easily), structs have to be hard coded in.
Check out one of the example projects:
- anonaddy-sequoia - Sequoia encryption PHP extension.
- opus-php - Audio encoder for the Opus codec in PHP.
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.
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
- 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.
Modules
Functions relating to the Zend Memory Manager, used to allocate request-bound memory.
Builder and objects relating to function and method arguments.
A pointer type for heap allocation using the Zend memory manager.
Structures that are used to construct other, more complicated types. Generally zero-cost abstractions.
Types and traits used for registering classes with PHP.
closure
Types and functions used for exporting Rust closures to PHP.
Types and traits for registering constants in PHP.
Traits used to convert between Zend/PHP and Rust types.
Types used to describe downstream extensions. Used by the cargo-php
CLI application to generate PHP stub files used by IDEs.
Error and result types returned from the library functions.
Types and functions used for throwing exceptions from Rust to PHP.
Raw FFI bindings to the Zend API.
Flags and enums used in PHP and the Zend engine.
Macros for interacting with PHP, mainly when the function takes variadic arguments. Unforutunately, this is the best way to handle these. Note that most of these will introduce unsafe into your code base.
A module typically glob-imported containing the typically required macros and imports.
Types and traits for adding properties to PHP classes registered from Rust.
Traits and types for interacting with reference counted PHP types.
Types defined by the Zend engine used in PHP.
Types used to interact with the Zend engine.
Macros
Attempts to call a given PHP callable.
Implements a set of traits required to convert types that implement
RegisteredClass
to and from ZendObject
s and Zval
s. Generally,
this macro should not be called directly, as it is called on any type that
uses the php_class
macro.
Ends the PHP extension information table. Must be run after all rows have been inserted into the table.
Sets the header for the PHP extension information table. Takes as many string arguments as required.
Adds a row to the PHP extension information table. Takes as many string arguments as required.
Starts the PHP extension information table displayed when running
phpinfo();
Must be run before rows are inserted into the table.
Parses a given list of arguments using the ArgParser
class.
Throws an exception and returns from the current function.
Constants
ext-php-rs
version.
Attribute Macros
Annotates a struct that will be exported to PHP as a class.
Attribute used to annotate constants to be exported to PHP.
Attribute used to annotate extern
blocks which are deemed as PHP
functions.
Attribute used to annotate a function as a PHP function.
Annotates a structs impl
block, declaring that all methods and constants
declared inside the impl
block will be declared as PHP methods and
constants.
Annotates a function that will be used by PHP to retrieve information about the module.
Annotates a function that will be called by PHP when the module starts up. Generally used to register classes and constants.