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) | string | char *s + size_t l |
| Z_PARAM_LONG(n) | int | zend_long n |
| Z_PARAM_DOUBLE(d) | float | double d |
| Z_PARAM_BOOL(b) | bool | bool b |
| Z_PARAM_ARRAY(a) | array | zval *a(HashTable 要再取一层) |
| Z_PARAM_OBJECT(o) | object | zend_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 |
参考文档
- Primers 编程伙伴/C/API 帮助手册/stdio.h
- Primers 编程伙伴/C/API 帮助手册/string.h
- Primers 编程伙伴/C/标准库/strlen
- Primers 编程伙伴/C/标准库/printf
- Primers 编程伙伴/C/标准库/strcmp
- Primers 编程伙伴/Bash/帮助手册/grep
- Primers 编程伙伴/Bash/帮助手册/local
