84aaa07d3e
* Remove uses of `unwrap`, improve library safety * Started work on `#[php_function]` attribute * Added `PhantomData` to `ZendHashTable` Proper lifetimes for `HashTable` type * `#[php_function]` now accepts `Vec<T>` Refactored `ZendHashTable` iterators - there is now `Iter` and `IntoIter` depending on whether it will consume the HashTable or not. * Add support for nullable types * Allow `optional` parameter on attribute * Support primitive and `Option` return types * Tidied and refactored attribute * Added documentation for `#[php_function]` Implemented `IntoZval` for `Option<T>` when `IntoZval` is also implemented for `T`. `None` resolves to `null`. * Added `#[php_method]` attribute * Added `Callable` type, implemented `Drop` on `Zval` While implementing `Drop`, the `Copy` derivation was removed, however, this should not have been there in the first place (`Zval` is not valid for `Copy` if it contains a string). * Added some macro functions to example * Add support for boolean arguments * Added wrapper around binary data Future support for binary arguments with `#[php_function]` macros. Unpacking binary data is no longer unsafe. It was never really unsafe in the beginning, as we were always reading valid memory, just the contents of the data could not be trusted. * Added `#[php_module]` attribute, added support for binary arguments * Added defaults for functions * Add defaults for methods * Add startup function macro and prelude * Refactored method adding Now done through impl attribute * Don't rename functions - generate another internal fn Also hide all generated functions from docs * Generate startup function when not already defined * Add support for class and global constants * Updated `skel` project * Updated macro documentation, added executor globals * Remove `Copy` bound for HashMap to Zval * Updated documentation * Add `FromZval` trait, updated docs * Fixed clippy lints * Fixed ZTS executor globals * Fix clippy lint
4.0 KiB
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::*;
#[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
}
Calling the function from PHP:
var_dump(hello_world("David")); // string(13) "Hello, David!"
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
IntoZvalandFromZvalfor 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 project is documented in-line, so viewing the cargo documentation is the best resource at the moment.
We are currently unable to deploy our documentation to docs.rs due to the crate requiring PHP 8.0, which is unavailable in the default Ubuntu repositories.
Documentation can be viewed here. It is generated from the latest master branch. Documentation will be moved to docs.rs when Ubuntu updates its repositories to PHP 8.0.
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:
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:
- ext-skel - Testbed for testing the library. Check out previous commits as well to see what else is possible.
- anonaddy-sequoia - Sequoia encryption PHP extension.
- opus-php - Work-in-progress extension to use the Opus library 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.