Zend API 的跨版本兼容层设计：论如何编写一套代码支持从 PHP 8.0 到 8.4

女士们，先生们，欢迎来到 PHP 扩展开发的“修罗场”。

请把手里的鼠标放下，暂时忘掉那些优雅的 foreach 和漂亮的 Laravel 集合，今天我们要聊的是底层的、血淋淋的、却又无比迷人的 C 语言世界。我是你们今晚的向导，一个在 Zend Engine 的代码海洋里溺水过好几次的老水手。

我们今天的主题是：《Zend API 的跨版本兼容层设计：论如何编写一套代码支持从 PHP 8.0 到 8.4》。别被这标题吓到了，虽然听起来像是在试图写一套代码让诺基亚还能跑 Windows 11，但在 PHP 这位“情绪多变的女友”面前，只要我们操作得当，虽然不能让所有版本都变乖，但至少能保证大家都不至于因为版本不兼容而分手。

想象一下，PHP 8.0 就像是个叛逆的青春期少年，8.1 是个加了过量咖啡因的工程师，8.2 是个试图发明新语的大师，而 8.4……嗯，8.4 可能正试图把整台服务器变成一台 ATM 机。我们的任务，就是用 C 语言的针线，把这些版本参差不齐的代码缝在一起，做成一件既保暖又时髦的“跨版本兼容层”。

第一章：zval 的暴动与结构的裂变

在 PHP 8.0 之前，zval 是什么？它是一个结构体。对，就是那种你可以想象成一个个格子，里面装着整数、字符串或者引用的结构体。它有一个 value 联合体，存放实际数据，还有一个 u1 和 u2 存放类型标记和引用计数。

但是，PHP 8.0 的工程师们——这群人大概觉得 zval 的结构体设计不够紧凑，或者纯粹是觉得“旧代码太丑了”，决定对 zval 进行了一次外科手术，甚至是一次截肢手术。他们引入了 zend_value，把原来的联合体彻底打散，变成了结构体。这不仅仅是改名，这是 ABI（二进制接口）的灾难。

如果你直接在 PHP 8.4 上编译一个基于 PHP 7.4 的旧扩展，你会看到编译器报出一堆关于内存对齐和结构体布局不一致的错误。这就像是你在法拉利的引擎盖下塞了一辆老式自行车的链条。

实战代码示例：

// 假设我们在设计一个兼容层，需要处理 zval 的获取

// 旧版本 (PHP 7.4 及以下)
ZEND_FUNCTION(legacy_get_value) {
    zval *value_arg;
    // 这里的 value 是 zval 结构体中的联合体成员
    // 我们需要获取它的类型和内容
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "z", &value_arg) == FAILURE) {
        RETURN_NULL();
    }

    if (Z_TYPE_P(value_arg) == IS_LONG) {
        // Z_LVAL_P 宏在 PHP 8.0 中已经变成了 ZEND_VALUE_LONG(value_arg)
        // 但为了兼容，我们需要写宏
        RETURN_LONG(ZEND_VALUE_LONG(value_arg));
    }
}

而在 PHP 8.0+，事情变得更复杂了。为了跨版本兼容，我们不能直接使用 Z_LVAL_P，因为那个宏在 8.0 里已经变了。我们必须使用 Z_LVAL_P 吗？不，我们需要使用 Z_LVAL_P 吗？不，我们需要使用 ZEND_VALUE_LONG 吗？

不，最稳妥的方式是使用 版本检测宏。这是兼容层的基石。

ZEND_FUNCTION(safe_get_value) {
    zval *value_arg;
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "z", &value_arg) == FAILURE) {
        RETURN_NULL();
    }

    // 这是一个经典的兼容层技巧
    // 检查 PHP 版本号
    if (PHP_VERSION_ID >= 80000) {
        if (Z_TYPE_P(value_arg) == IS_LONG) {
            RETURN_LONG(Z_LVAL_P(value_arg)); // 8.0+ 中这个宏兼容了旧用法
        }
    } else {
        if (Z_TYPE_P(value_arg) == IS_LONG) {
            RETURN_LONG(Z_LVAL_P(value_arg)); // 旧版用法
        }
    }
}

注意： 看到了吗？我们写了重复的代码。在 C 语言的世界里，重复是万恶之源，但为了生存，我们别无选择。或者，我们可以用 #ifdef 把它们包裹起来。

第二章：zend_parse_parameters 的严格模式与不信任

PHP 8.0 引入了严格类型检查，这是为了让你在写 PHP 代码时不再写 if (is_string($a)) 这种像瑞士奶酪一样的代码。但在 C 扩展里，zend_parse_parameters 是我们的命门。

在 PHP 8.0 之前，zend_parse_parameters 是非常宽容的“老好人”。你给它传一个 z（zval 指针），无论它是字符串、整数还是那个该死的 NULL，它通常都会尝试转换，或者直接吃掉它。这导致了很多扩展在没有严格模式下隐藏了 Bug。

PHP 8.0 改变了这个规则。默认情况下，如果你传了一个错误的类型，它不会转换，而是直接报错并返回 FAILURE。这就像是你以前让女朋友随你怎么填空，现在她只接受特定的答案，否则直接给你一巴掌。

实战代码示例：

假设我们写一个函数，期望接收一个整数。

// 旧写法：在 PHP 7.4 中，如果你传 "hello"，它可能会转换，或者忽略，取决于实现
// PHP 8.0+：这会直接报错 "Parameter #1 $num expects int, string given"

ZEND_FUNCTION(super_add) {
    zend_long num;

    // 默认模式：严格模式
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "l", &num) == FAILURE) {
        RETURN_THROWS(); // PHP 8.0+ 推荐写法
    }

    RETURN_LONG(num + 1);
}

现在，如果我们想兼容 PHP 8.0 之前的“宽容”行为，我们需要手动处理错误，或者使用 zend_parse_parameters_ex 来关闭严格检查。

ZEND_FUNCTION(lenient_add) {
    zend_long num = 0;
    zval *arg;

    // 使用 ZEND_PARSE_PARAMETERS_EX 来禁用严格模式
    // 但这也意味着你必须手动检查类型
    if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_STRICT, ZEND_NUM_ARGS(), "z", &arg) == FAILURE) {
        RETURN_THROWS();
    }

    if (Z_TYPE_P(arg) == IS_LONG) {
        num = Z_LVAL_P(arg);
    } 
    // 这里你可以决定是否要转换 "5" -> 5
    else if (Z_TYPE_P(arg) == IS_STRING) {
        // 糟糕，这里要处理字符串转数字
        // 并且要注意 PHP 8.0+ 的溢出处理
        num = strtol(Z_STRVAL_P(arg), NULL, 10);
    }

    RETURN_LONG(num + 1);
}

这就是兼容层的痛苦所在。你需要在 C 层面实现 PHP 8.0+ 试图在语言层面实现的严格性，同时还要照顾那些写了一堆垃圾 PHP 代码的旧版用户。

第三章：zend_object 结构体的重构

如果你在写一个面向对象的扩展（这在现代 PHP 开发中是常态），那么 zend_object 结构体就是你最大的噩梦。PHP 8.0 对这个结构体进行了大刀阔斧的修改。

在 PHP 7.4 中，properties 是直接存储在 zend_object 里面的一个哈希表。但在 PHP 8.0+ 中，为了性能优化（把对象属性和对象本身分开存储），zend_object 现在只有一个指针 properties，指向动态分配的属性表。

这意味着，如果你在 PHP 8.0+ 上定义了一个类，然后在旧版扩展里试图直接访问它的属性，你需要处理内存布局的差异。

实战代码示例：

让我们看看如何安全地初始化一个对象。

typedef struct {
    zend_object std;
    char *data;
    int len;
} my_object;

static zend_object *my_object_create(zend_class_entry *ce) {
    my_object *intern = zend_object_alloc(sizeof(my_object), ce);
    zend_object_std_init(&intern->std, ce);
    object_properties_init(&intern->std, ce);

    // 在 PHP 8.0+ 中，&intern->std.properties 就是属性表
    // 在 PHP 8.0 之前，这个结构体里的布局不同，但宏保证了兼容性
    intern->data = estrdup("Hello from the void");
    intern->len = strlen(intern->data);

    // 设置处理函数
    intern->std.handlers = &my_object_handlers;

    return &intern->std;
}

这里的关键是 zend_object_alloc 和 zend_object_std_init。这些是 Zend Engine 提供的 API 封装，它们内部已经处理了不同版本之间的差异。作为扩展开发者，你的工作就是正确调用它们。

但是，当你需要操作属性时，事情就变得有趣了。在 PHP 8.4 中（假设我们要支持的未来版本），PHP 引入了“原生类型化属性”，这意味着 C 层面可以定义属性类型（如 int, string），并自动进行类型检查，无需依赖反射。

这对我们的兼容层提出了新的挑战：我们需要判断当前引擎是否支持原生类型化属性，如果支持，就启用自动类型检查；如果不支持，就回到老路，使用 zend_hash_find 手动查找属性值。

static void my_object_read_property(zval *object, zval *member, int type, void **cache_slot, zval *retval) {
    // 这里的逻辑非常复杂，涉及到判断 member 是字符串还是枚举
    // PHP 8.4 可能会简化这个过程
}

第四章：Fiber（协程）的幽灵

PHP 8.1 引入了 Fiber。在 C 扩展里，这意味着你的代码可能会在完全没有警告的情况下，被 Fiber 的上下文切换所打断。

如果你在扩展里使用了全局变量，或者对某些资源进行了独占锁定，而在 Fiber 切换点之前没有正确保存状态，那么你的扩展就会导致 PHP 进程崩溃。这在 PHP 8.0 时代是不会发生的。

实战代码示例：

假设我们有一个扩展，它维护了一个全局的连接池。

static zend_resource *global_pool = NULL;

ZEND_FUNCTION(get_connection) {
    // 危险！如果在 Fiber 上下文中调用，global_pool 可能会被意外修改
    // 而 PHP 8.0 不会提醒你 Fiber 存在
    if (global_pool == NULL) {
        global_pool = (zend_resource*)emalloc(sizeof(zend_resource));
    }

    RETVAL_RES(global_pool);
}

在 PHP 8.1+ 中，你需要检查 EG(current_execute_data)->function_state.function->common.fn_flags & ZEND_ACC_CLOSURE 之类的标志来判断是否在 Fiber 中（这非常 hacky，因为 API 没有直接暴露）。

更安全的做法是使用 PHP 8.2+ 引入的 Fiber API，或者在代码中明确检查 Fiber 状态。当然，最完美的兼容层做法是：禁用 Fiber（如果可能），或者极其小心地处理状态。

// PHP 8.2+ 提供了 zend_fiber_get_current()，但在 8.0 中没有
#ifdef HAVE_FIBER
    if (zend_fiber_get_current()) {
        // 抛出错误，告诉用户 "Bro, your extension doesn't support Fiber yet"
        zend_throw_error(NULL, "Fiber support is not implemented in this extension yet");
        RETURN_FALSE;
    }
#endif

第五章：构建系统与 config.m4 的炼金术

现在我们知道了如何写 C 代码来应对版本差异，接下来我们如何让这些代码在不同的 PHP 版本下编译？这就需要 config.m4 这个魔法文件。

我们不能假设用户安装了 PHP 8.4，也许他们还在用 Docker 里的 PHP 8.0。所以，我们需要编写检测逻辑。

实战代码示例：

PHP_ARG_WITH([myext],
  [for myext support],
  [AS_HELP_STRING([--with-myext],
    [Enable myext support])],
  [no])

if test "$PHP_MYEXT" != "no"; then
  dnl 检测 PHP 版本
  PHP_EVAL_INCLINE([`$PHP_CONFIG --include-path`])
  PHP_EVAL_LIBS([`$PHP_CONFIG --libs`])

  dnl 编译 C 源码
  PHP_NEW_EXTENSION(myext, myext.c, $ext_shared,, -DZEND_ENABLE_STATIC_TSRMLS_CACHE=1)

  dnl PHP 8.4+ 的特殊处理：如果我们需要支持原生类型化属性
  dnl 这需要编译器支持 C11 或更高，以及 PHP 引擎开启该特性
  dnl 通常我们不需要手动控制，但如果你需要链接特定的库...

  dnl 检测 PHP 大版本
  AC_MSG_CHECKING([for PHP major version])
  PHP_VERSION=`$PHP_CONFIG --version`
  PHP_MAJOR_VERSION=`echo $PHP_VERSION | cut -d. -f1`
  AC_MSG_RESULT($PHP_MAJOR_VERSION)

  dnl 在 config.h 中定义版本号，供 C 代码使用
  if test "$PHP_MAJOR_VERSION" -ge 8; then
    AC_DEFINE([PHP_MYEXT_SUPPORTS_ZVAL_RENAME], [1], [Supports renamed zval structure])
  fi
fi

第六章：构建兼容层（终极解决方案）

理论讲完了，现在让我们来构建那个传说中的“兼容层”。

核心思路是：封装。

不要让直接调用 Zend API。创建一个中间层。就像你不能直接和不懂英语的外国人说话，你需要一个翻译。

我们定义一个 MYEXT_API，它根据编译时的 PHP_VERSION_ID 选择不同的实现。

实战代码示例：

#include "php.h"
#include "ext/standard/info.h"

// 1. 定义一个兼容的函数签名
// 我们假设我们需要一个函数来连接两个字符串，支持 PHP 8.0-8.4

#define MYEXT_API_VERSION 1

PHP_FUNCTION(myext_concat) {
    char *arg1, *arg2;
    size_t arg1_len, arg2_len;

    // 2. 在这里使用兼容的参数解析方式
    // 即使 PHP 8.4 改了 zend_parse_parameters，我们这里保持一致调用
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "ss", &arg1, &arg1_len, &arg2, &arg2_len) == FAILURE) {
        RETURN_THROWS();
    }

    // 3. 内存分配：在 PHP 8.0+ 中，我们需要区分堆和栈内存
    // 但 PHP 的 RETVAL_STRINGL 通常能处理，只要我们使用正确的宏

    // 4. 处理逻辑（这里简化，实际可能涉及类型检查）
    if (arg1_len + arg2_len > 0) {
        // 这里的赋值方式在 PHP 8.0+ 是安全的
        RETVAL_STRINGL(arg1, arg1_len);
        // 拼接 arg2
        // 注意：在 PHP 8.0+ 中，直接操作 RETVAL_STRINGL 的内部指针很危险
        // 所以最好的方式是重新分配内存
        char *result = emalloc(arg1_len + arg2_len + 1);
        memcpy(result, arg1, arg1_len);
        memcpy(result + arg1_len, arg2, arg2_len);
        result[arg1_len + arg2_len] = '';

        // 覆盖之前的 RETVAL_STRINGL 分配的内容
        // 注意：RETVAL_STRINGL 默认会 emalloc，我们需要先获取它释放掉，或者直接用 RETVAL_NEW_STR
        // 为了兼容性，我们这里使用 RETVAL_NEW_STR 来处理新分配的字符串
        zval_ptr_dtor(return_value); // 释放之前的
        RETVAL_NEW_STR(zend_string_init(result, arg1_len + arg2_len, 0));
        efree(result);
    } else {
        RETURN_EMPTY_STRING();
    }
}

但是，如果 PHP 8.4 改变了 zend_string 的内部结构（例如，它现在是一个结构体而不是指针），那么 RETVAL_STRINGL 这个宏可能会失效。所以，我们必须封装它。

static zend_string* myext_compat_zend_string_init(const char *str, size_t len, int persistent) {
#ifdef ZEND_USE_CONST_STRINGS
    // PHP 8.4 可能会使用常量字符串池优化
    return zend_string_init(str, len, persistent);
#else
    return zend_string_init(str, len, persistent);
#endif
}

PHP_FUNCTION(myext_concat_safe) {
    char *arg1, *arg2;
    size_t arg1_len, arg2_len;

    if (zend_parse_parameters(ZEND_NUM_ARGS(), "ss", &arg1, &arg1_len, &arg2, &arg2_len) == FAILURE) {
        RETURN_THROWS();
    }

    if (arg1_len + arg2_len > 0) {
        // 使用我们封装的函数
        RETVAL_NEW_STR(myext_compat_zend_string_init(arg1, arg1_len, 0));
        // ... 拼接逻辑
    } else {
        RETURN_EMPTY_STRING();
    }
}

第七章：处理 PHP 8.4 的“原生类型化属性”

这是 PHP 8.4（或接近 8.4 的版本）带来的最大变革。PHP 引擎将原生支持在 C 层定义类的类型化属性。

这意味着，你的扩展不再需要像以前那样通过反射来强制类型检查，或者通过 zend_hash_find 去遍历 properties_info。

实战代码示例：

假设我们定义一个类 MyClass，并在 C 层定义它的属性。

ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_myclass_constructor, 0, 1, IS_VOID, 0)
    ZEND_ARG_TYPE_INFO(0, name, IS_STRING, 0)
ZEND_END_ARG_INFO()

ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_myclass_get_name, 0, 0, IS_STRING, 0)
ZEND_END_ARG_INFO()

static zend_function_entry myclass_methods[] = {
    PHP_ME(MyClass, __construct, arginfo_myclass_constructor, ZEND_ACC_PUBLIC)
    PHP_ME(MyClass, getName, arginfo_myclass_get_name, ZEND_ACC_PUBLIC)
    PHP_FE_END
};

static const zend_class_entry myclass_ce_entry = {
    std_object_handlers,
    "MyClass",
    sizeof(zend_class_entry),
    myclass_methods
};

// 在 module startup 中注册类
PHP_MINIT_FUNCTION(myext) {
    zend_class_entry ce;
    INIT_CLASS_ENTRY(ce, "MyClass", myclass_methods);
    myclass_ce = zend_register_internal_class(&ce);
    return SUCCESS;
}

关键在于 arginfo。在 PHP 8.0-8.3，arginfo 告诉 PHP 引擎如何解析参数。在 PHP 8.4，如果引擎原生支持类型化属性，那么在 C 代码中定义属性时，参数检查可能会由引擎自动完成。

兼容策略：

如果你想让你的扩展支持 PHP 8.0-8.4，你不能直接依赖 8.4 的新特性。你必须检查 ZEND_ACC_TYPE_HINT 标志是否被设置，或者检查是否支持原生类型化。

但是，作为一个“资深专家”，我会告诉你一个更简单的办法：写一套通用的 arginfo。

在 PHP 8.0+，IS_STRING 或 IS_LONG 的 arginfo 定义方式基本上没有太大变化。PHP 8.4 可能会增加新的类型，比如 IS_ARRAY（原生类型化属性），但基础的字符串和整数处理逻辑是一致的。

// 定义一个兼容所有版本的 getter
ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_myclass_get_name_compat, 0, 0, IS_STRING, 0)
    // 即使在 8.4 中，IS_STRING 也是安全的
ZEND_END_ARG_INFO()

所以，不要试图去预测 PHP 8.4 的每一个新特性。你应该关注的是ABI 的稳定性。PHP 的扩展机制之所以能存在这么多年，很大程度上是因为 Zend Engine 对 C 接口保持了惊人的向后兼容性。虽然 zval 结构变了，但宏（ZVAL_STR, ZEND_VALUE_LONG）更新了；虽然 zend_object 改了，但 zend_object_std_init 还在。

第八章：错误处理与 Denoising

PHP 8.3 引入了“Denoising”，这是一种错误处理机制。它让错误处理更加显式，不再那么“模糊不清”。

在旧版本中，zend_error() 可能会直接输出到 stderr 并终止脚本。在新版本中，你可以更精细地控制错误报告。

在 C 扩展中，这意味着你需要更多地使用 zend_throw_error() 和 zend_throw_exception()。

实战代码示例：

ZEND_FUNCTION(myext_divide) {
    zend_long a, b;

    if (zend_parse_parameters(ZEND_NUM_ARGS(), "ll", &a, &b) == FAILURE) {
        RETURN_THROWS();
    }

    if (b == 0) {
        // PHP 8.3+ 推荐写法
        zend_throw_error(NULL, "Division by zero");
        RETURN_FALSE;
    }

    RETURN_LONG(a / b);
}

如果你的扩展在 PHP 8.3 之前运行，zend_throw_error 不可用（虽然宏定义通常能处理）。你需要检查宏是否存在。

结语：在 C 语言中拥抱变化

好了，朋友们，我们的讲座接近尾声。

写一个支持 PHP 8.0 到 8.4 的扩展，就像是在走钢丝。你手里拿着 PHP 8.0 的旧图纸（遗留代码），脚下的桥是 PHP 8.4 的新木板（新 API）。你必须用条件编译作为安全带，用宏作为你的肌肉，用大量的注释作为你的导航仪。

记住几个核心原则：

1. 检查 PHP_VERSION_ID：这是你的 GPS。
2. 使用宏：不要直接访问结构体成员，除非你确定版本。
3. 封装 API 调用：不要让你的扩展直接暴露给 Zend API 的每一个小变动。
4. 保持冷静：当编译失败时，不要砸键盘。先检查 zval 的定义。

虽然 PHP 的内核在变，虽然 zend_value 的重构让人抓狂，虽然 PHP 8.4 试图用原生类型化属性把一切都变得“类型安全”，但只要我们遵循这些原则，我们就能用 C 语言编写出跨越版本的神奇代码。

毕竟，能写出兼容 PHP 8.0 和 8.4 的扩展，那是一种什么样的体验呢？那是一种在 C 语言的地狱里，手握三叉戟，劈开所有版本限制的快感。现在，拿起你的 config.m4，去征服那个庞大而混乱的 PHP 内核吧！