ext-php-rs

为在 Rust 中本地构建 PHP 扩展提供 Zend API 绑定和抽象。

• 文档：https://docs.rs/ext-php-rs
• 指南：https://davidcole1340.github.io/ext-php-rs

示例

导出简单的函数 function hello_world(string $name): string 到 PHP

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

use nicelocal_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
}

使用 cargo-php 构建 IDE 模板并安装扩展

$ 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
// ...

从 PHP 调用函数

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

更多示例请参阅库 指南。

功能

• 易于使用： 内置宏可以抽象出与 Zend API 交互的需求，例如 Rust 类型函数参数可以抽象出与 Zend 值的交互。
• 轻量级： 您不必使用内置的辅助宏。您可以在自己的函数周围编写自己的粘合代码。
• 可扩展： 实现 IntoZval 和 FromZval 以支持您自己的自定义类型，允许类型用作函数参数和返回类型。

目标

我们的主要目标是 使扩展开发更容易。

• 在 C 中编写扩展可能会很繁琐，而且由于 Zend API 的有限文档，可能会令人生畏。
• Rust 的现代语言特性和功能齐全的标准库在 C 上取得了重大改进。
• 抽象出原始的 Zend API 可以使扩展开发更快、更自信。
• 抽象还允许我们在不进行重大更改的情况下支持 PHP 的未来（和潜在过去）版本。

文档

库指南可以在 此处 阅读。

项目以行内方式进行文档编制，因此目前最好的资源是查看 cargo 文档。这可以在 docs.rs 上查看。

要求

• 基于 Linux、macOS 或 Windows 的操作系统。
• PHP 8.0 或更高版本。
  • 不打算支持 PHP 的早期版本。
• Rust。
  • 目前，我们不保证 MSRV，然而 lib.rs 在编写时建议 Rust 1.57。
• Clang 5.0 或更高版本。

Windows 要求

• 扩展只能编译自 https://windows.php.net 的 PHP 安装。最终计划支持其他安装。
• Windows 需要 Rust nightly 版本。这是由于一些 PHP 函数在 Windows 上使用 vectorcall 调用约定，这仅在 Rust 的 nightly 不稳定特性中可用。
• 建议使用 rust-lld 链接器来链接您的扩展。虽然支持 MSVC 链接器 (link.exe)，但如果链接器版本不受您的 PHP 安装支持，您可能会遇到问题。您可以通过创建包含以下内容的 .cargo\config.toml 文件来使用 rust-lld 链接器

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

• cc 仓库需要 cl.exe 在您的系统上。这通常与 Microsoft Visual Studio 一起提供。
• cargo-php 的存根生成功能在 Windows 上不可用。将此功能重写为跨平台功能正在路线图中。

Cargo 功能

默认情况下，所有功能都未启用。

• closure - 允许将 Rust 闭包返回到 PHP。创建了一个新的类类型，RustClosure。
• anyhow - 为 anyhow::Error 实现 Into<PhpException>，允许您从 PHP 函数返回 anyhow 结果。支持 anyhow v1.x。

用法

查看其中一个示例项目

• anonaddy-sequoia - Sequoia 加密 PHP 扩展。
• opus-php - Opus 编码器，用于 PHP 中的 Opus 编码。
• tomlrs-php - TOML 数据格式解析器。
• php-scrypt - scrypt 密码散列算法的 PHP 包装器。

贡献

非常欢迎贡献。我是一个 Rust 新手开发者，任何建议都欢迎。请通过 Github 自由地提交问题和 PR。

欢迎的贡献包括

• 文档扩展（尤其是示例！）
• 安全性审查（特别是如果您有 Rust 和 Zend API 的经验）。
• 错误修复和功能。
• 功能请求。

除非您明确声明，否则根据 Apache-2.0 许可证定义，任何有意提交以包含在您的工作中的贡献，都将双重许可如上所述，没有任何附加条款或条件。

资源

• PHP 内部书籍

许可

许可以下任一项

• Apache 许可证 2.0 (LICENSE_APACHE 或 http://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE_MIT 或 http://opensource.org/licenses/MIT)

任选。