PHP 8.3 写 C 扩展踩坑实录:从 phpize 到 zval,一篇跑通

作者:游鹄君日期:2026/9/30

php扩展开发-使用 C 语言编写高性能 PHP 扩展的底层编译与调用(zval 与内存管理)

以字符串加解密为例

前提

^ 是什么?——异或(XOR)

C 里的 ^ 不是乘方,是按位异或:两个二进制位不同则 1,相同则 0

11 ^ 1 = 0
21 ^ 0 = 1
30 ^ 1 = 1
40 ^ 0 = 0
5
6

对一个字节操作时,就是 8 个 bit 逐位做这个运算。比如字符 ‘A’ 和 ‘k’:

1'A' = 0x41 = 0 1 0 0 0 0 0 1
2'k' = 0x6B = 0 1 1 0 1 0 1 1
3───────────────────────────── XOR
4结果     = 0 0 1 0 1 0 1 0 = 0x2A = '*'
5
6

为什么 XOR 能加密?——一个魔法性质
XOR 有个黄金定律:同一个数异或两次,等于没动。

1x ^ k ^ k = x
2
1密文 = 'A' ^ 'k' = 0x2A      ← 加密
20x2A ^ 'k'     = 'A'          ← 再异或一次同样的 k,明文回来了!
3

所以

1加密:密文[i] = 明文[i] ^ 密钥[i]
2解密:明文[i] = 密文[i] ^ 密钥[i]   ← 一模一样的操作!
3
先看纯C的例子

:::tip
这是docker中的Linux环境
:::

test/xor_test.c

1#include <stdio.h>
2#include <string.h>
3
4int main(void)
5{
6	char data[] = "HELLO";
7	char key[] = "KEY";
8	size_t key_len = strlen(key);
9	char out[6];
10	// 加密
11	for (int i = 0; i < 5; i++)
12	{
13		out[i] = data[i] ^ key[i % key_len];
14	}
15	out[5] = '\0';
16	printf("密文(可能不可见): ");
17	for (int i = 0; i < 5; i++) printf("%02X ", (unsigned char)out[i]);
18    printf("\n");
19
20	 /* 解密:同样的循环再来一遍 */
21    for (int i = 0; i < 5; i++) {
22        out[i] = out[i] ^ key[i % key_len];
23    }
24    printf("解密: %s\n", out);
25
26    return 0;
27}
28

:::warning
注意密文第二个字节是 00(NUL 字节)!
如果用 printf("%s", out) 打印密文,会碰到 NUL 就截断,屏幕上一片空白,看起来像加密失败了。
这就是为什么 PHP 字符串必须记长度(len)而不是靠 \0 结尾——二进制安全。下面的 yh_encrypt 返回值可能包含任意字节,扩展层必须正确处理长度。
:::

之后执行

-o 指定输出文件名

1gcc -o xor_test xor_test.c && ./xor_test
2

或者

-O2(优化等级2)-Wall(显示所有警告)

1gcc -O2 -Wall -o xor_test xor_test.c && ./xor_test
2

如下图所见可以看到密文又原样显示出来了

还是以youhujun(demo)扩展为例

修改youhujun/youhujun.stub.php

1
2<?php
3/**
4 * @generate-class-entries
5 * @undocumentable
6 */
7
8function yh_p(mixed $param): void {}
9
10function yh_encrypt(string $data, string $key): string {}
11
12function yh_decrypt(string $data, string $key): string {}
13
14

之后

1php build/gen_stub.php youhujun.stub.php
2

显示:# Saved youhujun_arginfo.h

:::danger
XOR 只是学习参考示例——相同明文+相同密钥必然得到相同密文,无完整性校验,真实代码加密必须用 AES + HMAC
:::

再修改youhujun.c

1/* youhujun extension for PHP */
2
3#ifdef HAVE_CONFIG_H
4# include "config.h"
5#endif
6
7#include "php.h"
8#include "main/SAPI.h" 
9#include "Zend/zend_exceptions.h"    
10#include "ext/standard/info.h"
11#include "php_youhujun.h"
12#include "youhujun_arginfo.h"
13
14/* For compatibility with older PHP versions */
15#ifndef ZEND_PARSE_PARAMETERS_NONE
16#define ZEND_PARSE_PARAMETERS_NONE() \
17	ZEND_PARSE_PARAMETERS_START(0, 0) \
18	ZEND_PARSE_PARAMETERS_END()
19#endif
20
21
22PHP_FUNCTION(yh_p)
23{
24	zval *param;
25
26	ZEND_PARSE_PARAMETERS_START(1, 1)
27		Z_PARAM_ZVAL(param)
28	ZEND_PARSE_PARAMETERS_END();
29
30	if (strcmp(sapi_module.name, "cli") != 0) {
31		php_printf("<pre>");
32	}
33
34	zend_print_zval_r(param, 0);
35
36	if (strcmp(sapi_module.name, "cli") != 0) {
37		php_printf("</pre>");
38	}
39
40}
41
42PHP_FUNCTION(yh_encrypt)
43{
44    char *data, *key;
45    size_t data_len, key_len;
46    zend_string *result;
47
48    // 取两个字符串参数(Z_PARAM_STRING x2)
49	ZEND_PARSE_PARAMETERS_START(2, 2)
50		Z_PARAM_STRING(data, data_len)
51		Z_PARAM_STRING(key, key_len)
52	ZEND_PARSE_PARAMETERS_END();
53
54    if (key_len == 0) {
55		zend_throw_error(zend_ce_value_error, "Key cannot be empty");
56		return;
57	}
58
59	//分配内存
60	result = zend_string_alloc(data_len, 0);
61    
62	for(size_t  i = 0 ; i < data_len; i++)
63	{
64		ZSTR_VAL(result)[i] = data[i] ^ key[i % key_len];
65	}
66
67	RETURN_STR(result);
68}
69
70PHP_FUNCTION(yh_decrypt)
71{
72    char *data, *key;
73    size_t data_len, key_len;
74    zend_string *result;
75
76    // 取两个字符串参数(Z_PARAM_STRING x2)
77	ZEND_PARSE_PARAMETERS_START(2, 2)
78		Z_PARAM_STRING(data, data_len)
79		Z_PARAM_STRING(key, key_len)
80	ZEND_PARSE_PARAMETERS_END();
81
82	if (key_len == 0) {
83		zend_throw_error(zend_ce_value_error, "Key cannot be empty");
84		return;
85	}
86	//分配内存
87	result = zend_string_alloc(data_len, 0);
88    
89	for(size_t  i = 0 ; i < data_len; i++)
90	{
91		ZSTR_VAL(result)[i] = data[i] ^ key[i % key_len];
92	}
93
94	RETURN_STR(result);
95}
96
97
98/* {{{ PHP_RINIT_FUNCTION */
99PHP_RINIT_FUNCTION(youhujun)
100{
101#if defined(ZTS) && defined(COMPILE_DL_YOUHUJUN)
102	ZEND_TSRMLS_CACHE_UPDATE();
103#endif
104
105	return SUCCESS;
106}
107/* }}} */
108
109/* {{{ PHP_MINFO_FUNCTION */
110PHP_MINFO_FUNCTION(youhujun)
111{
112	php_info_print_table_start();
113	php_info_print_table_row(2, "youhujun support", "enabled");
114	php_info_print_table_end();
115}
116/* }}} */
117
118/* {{{ youhujun_module_entry */
119zend_module_entry youhujun_module_entry = {
120	STANDARD_MODULE_HEADER,
121	"youhujun",					/* Extension name */
122	ext_functions,					/* zend_function_entry */
123	NULL,							/* PHP_MINIT - Module initialization */
124	NULL,							/* PHP_MSHUTDOWN - Module shutdown */
125	PHP_RINIT(youhujun),			/* PHP_RINIT - Request initialization */
126	NULL,							/* PHP_RSHUTDOWN - Request shutdown */
127	PHP_MINFO(youhujun),			/* PHP_MINFO - Module info */
128	PHP_YOUHUJUN_VERSION,		/* Version */
129	STANDARD_MODULE_PROPERTIES
130};
131/* }}} */
132
133#ifdef COMPILE_DL_YOUHUJUN
134# ifdef ZTS
135ZEND_TSRMLS_CACHE_DEFINE()
136# endif
137ZEND_GET_MODULE(youhujun)
138#endif
139
140

同一个函数实现,这就是 XOR 自逆性在工程上的体现

编译

之后

1make
2

确认扩展本身能不能加载

1php -d extension=modules/youhujun.so -m | grep youhujun
2

可以看到已经有了youhujun

测试

验证加密

1php -d extension=modules/youhujun.so -r 'var_dump(bin2hex(yh_encrypt("游鹄君", "abcd")));'
2
3

验证解密

1php -d extension=modules/youhujun.so -r '
2$s = "游鹄君";
3$key = "abcd";
4$e = yh_encrypt($s, $key);
5var_dump(bin2hex($e));
6var_dump(yh_decrypt($e, $key) === $s);
7'
8

验证抛异常

1php -d extension=modules/youhujun.so -r 'yh_encrypt("abc", "");'
2


关于"内存没释放"的疑惑

代码里没有 leak,原因是 Zend 内存的两层机制:

  • zend_string_alloc 走 ZendMM,请求结束统一回收,忘了 RETURN 也不会永久泄漏(兜底)
  • 更关键的是 RETURN_STR(result) 把所有权移交给了引擎,由引擎管引用计数,变量被回收时自动释放
  • 这就是 C 扩展最容易踩坑的点:分配出来的东西,要么 RETURN 交给引擎,要么自己 zend_string_release(),必须二选一

报错处理 未定义标识符 "zend_ce_value_error"C/C++(20)

排错套路参考:C扩展开发通用排错套路-未定义标识符 xxx

查找zend_ce_value_error声明位置

1grep -rn "zend_ce_value_error" /usr/local/php/include/php/ --include="*.h"
2

/usr/local/php/include/php/Zend/zend_exceptions.h:35:extern ZEND_API …

加上引用

1#include "Zend/zend_exceptions.h"  
2

zend_throw_error 自己声明在 Zend/zend.h(php.h 已经包含),所以不用管。只有 zend_ce_value_error 这个类指针变量需要额外 include——因为类指针在 PHP 8之前不存在,是 8.0 新加的

拓展

Z_PARAM_类型 取参数

宏PHP接收类型给到你的C变量
Z_PARAM_ZVAL§mixed(任意)zval *p
Z_PARAM_STRING(s, l)stringchar *s + size_t l
Z_PARAM_LONG(n)intzend_long n
Z_PARAM_DOUBLE(d)floatdouble d
Z_PARAM_BOOL(b)boolbool b
Z_PARAM_ARRAY(a)arrayzval *a(HashTable 要再取一层)
Z_PARAM_OBJECT(o)objectzend_object *o

进阶:Z_PARAM_OPTIONAL

1char *key = "default_key";
2size_t key_len = strlen(key);   // 或用 sizeof("default_key") - 1
3
4ZEND_PARSE_PARAMETERS_START(1, 2)
5	Z_PARAM_STRING(data, data_len)
6	Z_PARAM_OPTIONAL
7	Z_PARAM_STRING(key, key_len)
8ZEND_PARSE_PARAMETERS_END();
9
10

可选参数必须提前初始化默认值,宏不会帮你兜底

Zend API 全是这个套路,不止 Z_PARAM_ 一家,命名规律贯穿整个内核:

家族作用例子
Z_PARAM_*读取函数入参(本次学习的)Z_PARAM_LONG
Z_TYPE / Z_STRVAL / Z_LVAL拆解解析 zval 容器Z_LVAL_P(param)
RETVAL_* / RETURN_*设置返回值(RETURN直接返回;RETVAL设置之后还要return)RETURN_STR、RETVAL_LONG
ZSTR_*操作 zend_string 字符串对象ZSTR_VAL、ZSTR_LEN

参考文档


《PHP 8.3 写 C 扩展踩坑实录:从 phpize 到 zval,一篇跑通》 是转载文章,点击查看原文。


相关推荐


600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通
晨陌y2026/9/24

600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通 前言 我一直觉得二手商用迷你主机最有意思的地方,不是“花几百块假装买到 Mac mini”,而是它给了我一块成本不高、出问题也敢继续折腾的实验平台。真正的 Mac mini 在稳定性、系统支持和整体体验上更省心,这台 HP ProDesk 600 G4 Desktop Mini 没必要去硬碰硬比较;但如果目的只是体验 macOS、录教程、做轻量桌面环境,或者顺手跑一些本地服务,那么 600


给若依加审批流,不用 Flowable
mldong2026/9/16

引言 若依是国内最流行的快速开发框架之一,GitHub 镜像 4 万多 star,几乎每个 Java 后台项目都从它起步。但它有个大家都知道的"缺口":官方免费版不内置审批流。 用若依的人,迟早要碰审批——请假、报销、合同、采购。怎么补? 这篇文章给一个不绕弯子的答案:别上 Flowable,用 jeeflow。后端一个依赖一个薄壳,前端一个宿主组件九个薄页,配一条菜单 SQL,半天跑通一个带工作台、发起、待办、审批、流程设计器的完整流程中心。 我把整个过程真机走了一遍(若依 3.9.2 mas


Elasticsearch 中的查询重写规则:通配符扫描速度提升 2.3 倍
Elasticsearch2026/9/8

作者:来自 Elastic Parker Timmins, Martijn Van Groningen 第二条规则使空字符串过滤器的速度提升了 1.6 倍。它直接从偏移数组中读取字符串长度,完全不会访问压缩后的字节。这两条规则都源于同一种习惯:运行真实查询,并寻找特殊情况。 想获得 Elastic 认证?了解下一期 Elasticsearch 工程师培训何时开课!你现在可以开始免费云试用,或者立即在你的本地机器上试用 Elastic。 Lucene 查询重写规则让 Elasticsearch


六语言引擎实现对比:同构背后的妥协与差异
mldong2026/8/31

系列定位:jeeflow 系列第 11 篇(第三季「多语言联邦」第 3 篇 · 季终) 平台:掘金(深度对比)/ 公众号(故事线) 素材版本:引擎 Java 1.8.19 / Go·Python·Node 1.8.21 / PHP 1.3.6 / Rust 1.0.6(2026-08-30 六语言同日发版) 一、先看今天发生的一件事 写这篇的时候(2026-08-30),jeeflow 刚完成一次六语言同步发版:


Linux + Docker + FastAPI 工程化实践指南
卷无止境2026/8/23

一套稳健的 FastAPI 工程,不是把 API、Redis 和 PostgreSQL 塞进同一个 Compose 文件就算完事。更合理的做法是把应用设计成无状态服务,数据库迁移、配置管理、健康检查和测试各自承担清晰职责;开发环境追求反馈速度,生产环境则强调镜像可复现、最小权限和可观测性。 下面给出一套可以直接落地的项目骨架。 一、推荐架构 开发环境可以使用 Docker Compose 编排所有依赖,代码通过挂载目录实现热更新。生产环境仍然使用相同镜像,但不再挂载源代码,也不启用 --relo


把《天龙八部》装进向量数据库:EPUB加载、文本分块与RAG问答全链路实战
浮生望2026/8/10

摘要 以《天龙八部》EPUB拆解RAG全链路:EPubLoader章节加载、RecursiveCharacterTextSplitter分块、Milvus流式入库,实现语义问答。 一、一本百万字小说,如何让AI读懂它 上一篇文章我们用AI日记助手演示了RAG的基本流程:5篇日记、手动构造数据、一次插入。但真实场景中,数据源不是手动构造的,而是各种格式的文档——PDF、EPUB、CSV、Markdown。数据量也不是5条,而是百万字级别的小说。 这篇文章以金庸的《天龙八部》EPUB电子书为样本,


前端框架vue3,vite 开发前端项目实践步骤指南
慧一居士2026/8/1

Vue 3 + Vite 前端项目实践指南 适用版本(截至 2026 年 7 月):Vue 3.5+ | Vite 6/7 | TypeScript 5.6+ | Node.js ^20.19.0 || >=22.12.0 目标:从零搭建一个可投入生产的工程化项目,覆盖「初始化 → 架构 → 规范 → 联调 → 构建部署」全流程。 全景路线图 环境准备 ──▶ 脚手架创建 ──▶ 目录规划 ──▶ Vite 配置 ──▶ 路由/状态/请求层


Java Jersey 实战指南:用 JAX-RS 注解写清晰的 REST API
唐青枫2026/7/24

简介 Jersey 是 Jakarta RESTful Web Services 规范的一种实现。 老名字常叫 JAX-RS,新包名是: jakarta.ws.rs Jersey 自己的核心包名通常是: org.glassfish.jersey 简单理解: Jakarta REST / JAX-RS 是规范 Jersey 是实现 Spring Boot 提供 Jersey 自动配置和 starter Jersey 的开发方式是用注解把 Java 类声明成 HTTP 资源: @Path("/


数据结构之双链表
无忧.芙桃2026/7/16

本篇目标: 1. 学会关于双链表的相关操作 2. 了解链表和顺序表的区别和优点 一、双链表接口实现 1. 双向链表的结构 • 单链表的结点中保存了指向后继结点的地址,所以单链表中找当前结点的后继结点很容易,但要获取当前结点的前驱结点就很麻烦,就只能从头开始往后遍历获取,时间复杂度为 O(n);所以单链表中只有当前结点的指针 pos 时(没有头指针),想要在 pos 之前插入结点和删除 pos 位置结点都是无法实现的。 • 双向链表相比单链表最大的特征是每个结点中多了一个前驱指针,


Android 面试系列:Kotlin 协程的 delay 到底发生在哪个线程?
潜龙勿用之化骨龙2026/7/8

在开发中,我们经常写出这样的代码: mainScope.launch { log("start") delay(1000) log("end") } 这段代码看起来非常简单,但它隐藏了一个非常经典的问题: delay 这 1 秒到底发生在哪个线程? 主线程前后都在执行,那中间谁在“等时间”? 结论 delay 从来不占用线程等待,它是一次“挂起 + 时间注册 + 调度恢复 + 状态机推进”的过程。 中间没有任何业务线程在 sleep,也没有线程在阻塞计时。

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读