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 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 crate 需要 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 - PHP 中的 Opus 编码器的音频编码器。
• tomlrs-php - TOML 数据格式解析器。
• php-scrypt - scrypt 密码哈希算法的 PHP 包装器。

贡献

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

欢迎的贡献包括

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

除非您明确说明，否则任何有意提交给您的工作以包含在内的贡献，根据 Apache-2.0 许可证的定义，应如上双许可，不附加任何额外条款或条件。

资源

• PHP 内部书

许可证

以下任一许可下：

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

根据您的选择。