PHP 扩展开发的文章,我均已更新至《TIPI》(下面的博文可能已经过时,以 TIPI 上的内容为准)。
在阅读下面的内容之前,我们假定你已经对 PHP 7 基本的数据结构 都有大致的了解了,这是下面内容阅读的前提。
我们分为两大块:
首先实现一个自定义的文件打开、读取、写入、关闭的文件操作扩展;
然后分析各个操作背后的实现原理,其中某些部分的实现我会和 PHP 5.3 使用资源包裹第三方扩展源码解读 对比分析。
0 通过原型生成扩展骨架
首先进入到源码目录的ext
目录中,添加一个文件操作的原型文件
[root@localhost php-src-php-7.0.3]# cd ext/ [root@localhost ext]# vim tipi_file.proto
编辑原型为
resource file_open(string filename, string mode) string file_read(resource filehandle, int size) bool file_write(resource filehandle, string buffer) bool file_close(resource filehandle)
[root@localhost ext]# ./ext_skel --extname=tipi_file --proto=./tipi_file.proto
这样一个简单的文件操作扩展的代码骨架就生成了。
完整代码 tipi_file.c,可以先有一个大致的了解,这样后面阅读时,思路可能会清晰很多。
1 扩展的实现
1.1 注册资源类型
1.1.1 注册资源 API
ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, const char *type_name, int module_number)
参数 | 解释 |
ld | 释放该资源时调用的函数。 |
pld | 释放用于在不同请求中始终存在的永久资源的函数。 |
type_name | 是一个具有描述性类型名称的字符串。 |
module_number | 为引擎内部使用,当我们调用这个函数时,我们只需要传递一个已经定义好的module_number 变量。 |
该 API 返回一个资源类型 id,该id应当被作为全局变量保存在扩展里,以便在必要的时候传递给其他资源API。
1.1.2 添加资源释放回调函数
static void tipi_file_dtor(zend_resource *rsrc TSRMLS_DC){ FILE *fp = (FILE *) rsrc->ptr; fclose(fp); }
我们发现该函数的参数类型是zend_resource
。这是 PHP7 新增的数据结构,在 PHP 5 则是zend_rsrc_list_entry
。细节的内容,我们留在后面分析。
1.1.3 在PHP_MINIT_FUNCTION
中注册
我们知道在 PHP 生命周期中,当 PHP 被装载时,PHP_MINIT_FUNCTION
(模块启动函数)即被引擎调用。这使得引擎做一些例如资源类型,注册INI变量等的一次初始化。
那么我们需要在这里通过zend_register_list_destructors_ex
在PHP_MINIT_FUNCTION
来注册资源类型。
PHP_MINIT_FUNCTION(tipi_file) { /* If you have INI entries, uncomment these lines REGISTER_INI_ENTRIES(); */ le_tipi_file = zend_register_list_destructors_ex(tipi_file_dtor, NULL, TIPI_FILE_TYPE, module_number); return SUCCESS; }
其中TIPI_FILE_TYPE
在前面已经定义了,是该扩展的别名(具体可以对比着代码 tipi_file.c 查看)
1.2 注册资源
1.2.1 注册资源 API
在 PHP 7 中删除了原来的ZEND_REGISTER_RESOURCE
宏,直接使用zend_register_resource
函数
ZEND_API zend_resource* zend_register_resource(void *rsrc_pointer, int rsrc_type)
参数 | 解释 |
rsrc_pointer | 资源数据指针 |
rsrc_type | 注册资源类型时获得的资源类型 id |
1.2.2 在 file_open
函数中实现资源的注册
PHP_FUNCTION(file_open) { char *filename = NULL; char *mode = NULL; int argc = ZEND_NUM_ARGS(); size_t filename_len; size_t mode_len; if (zend_parse_parameters(argc TSRMLS_CC, "ss", &filename, &filename_len, &mode, &mode_len) == FAILURE) return; // 使用 VCWD 宏取代标准 C 文件操作函数 FILE *fp = VCWD_FOPEN(filename, mode); if (fp == NULL) { RETURN_FALSE; } RETURN_RES(zend_register_resource(fp, le_tipi_file)); }
其中RETURN_RES
宏的作用是将返回的zend_resource
添加到zval
中,然后将最后的zval
作为返回值。也就是说该函数的返回值为zval
指针。RETURN_RES(zend_register_resource(fp, le_tipi_file))
会将返回值的value.res
设为fp
,u1.type_info
设为IS_RESOURCE_EX
。大家可以根据源码非常直观的了解到,这里不粘贴代码详细说明了。
1.3 使用资源
1.3.1 使用资源 API
ZEND_API void *zend_fetch_resource(zend_resource *res, const char *resource_type_name, int resource_type)
在 PHP 7 中删除了原有的ZEND_FETCH_RESOURCE
宏,直接使用函数zend_fetch_resource
,而且解析方式也变得简单了很多,想比 PHP 5 要高效很多,后面我们再通过图片分析对比。
参数 | 含义 |
res | 资源指针 |
resource_type_name | 该类资源的字符串别名 |
resource_type | 该类资源的类型 id |
1.3.2 解析资源的实现
当我们要实现文件的读取时,最终还是需要使用原生的fread
函数,所以这里需要通过zend_fetch_resource
将zend_resource
解析成为该资源包裹的原始的FILE *
的指针。
PHP_FUNCTION(file_read) { int argc = ZEND_NUM_ARGS(); int filehandle_id = -1; zend_long size; zval *filehandle = NULL; FILE *fp = NULL; char *result; size_t bytes_read; if (zend_parse_parameters(argc TSRMLS_CC, "rl", &filehandle, &size) == FAILURE) return; if ((fp = (FILE *)zend_fetch_resource(Z_RES_P(filehandle), TIPI_FILE_TYPE, le_tipi_file)) == NULL) { RETURN_FALSE; } result = (char *) emalloc(size+1); bytes_read = fread(result, 1, size, fp); result[bytes_read] = '\0'; RETURN_STRING(result, 0); }
这里需要说明,脚本自动生成的扩展代码中还是使用ZEND_FETCH_RESOURCE
, 是个 BUG,因为自动生成的脚本(ext/skeleton/create_stubs
)还没更新。
与之类似的文件的写入操作,也很类似,这里就复制代码了,请查看完整的代码 tipi_file.c
1.4 资源的删除
1.4.1 资源删除 API
ZEND_API int zend_list_close(zend_resource *res)
传入需要被删除的资源即可。该 API 看似非常简单,实际做了很多工作,后面原理分析细说。
1.4.2 资源删除的实现
我们在函数file_close
中需要调用资源删除 API
PHP_FUNCTION(file_close) { int argc = ZEND_NUM_ARGS(); int filehandle_id = -1; zval *filehandle = NULL; if (zend_parse_parameters(argc TSRMLS_CC, "r", &filehandle) == FAILURE) return; zend_list_close(Z_RES_P(filehandle)); RETURN_TRUE; }
1.5 编译安装以及测试
1.5.1 编译安装
通过上面的编码,一个简单的第三方的扩展就实现了。查看完整版
下面的一些命令配置请根据自己的环境而定(安装的过程可以参考最基础的扩展开发教程)
[root@localhost tipi_file]# php7ize Configuring for: PHP Api Version: 20151012 Zend Module Api No: 20151012 Zend Extension Api No: 320151012 [root@localhost tipi_file]# ./configure --with-php-config=/usr/local/php7/bin/php-config ... [root@localhost tipi_file]# make ... [root@localhost tipi_file]# make install ...
1.5.2 测试
直接用 php 脚本测试,就不一个功能一个功能写测试样例了,修改tipi_file.php
文件。
$fp = file_open("./CREDITS","r+"); var_dump($fp); var_dump(file_read($fp,6)); var_dump(file_write($fp,"zhoumengakng")); var_dump(file_close($fp));
然后通过命令行执行
php7 -d"extension=tipi_file.so" tipi_file.php
2 源码分析
2.1 注册资源类型源码
ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, const char *type_name, int module_number) { zend_rsrc_list_dtors_entry *lde; zval zv; lde = malloc(sizeof(zend_rsrc_list_dtors_entry)); lde->list_dtor_ex = ld; lde->plist_dtor_ex = pld; lde->module_number = module_number; lde->resource_id = list_destructors.nNextFreeElement; lde->type_name = type_name; ZVAL_PTR(&zv, lde); if (zend_hash_next_index_insert(&list_destructors, &zv) == NULL) { return FAILURE; } return list_destructors.nNextFreeElement-1; }
其中
ZVAL_PTR(&zv, lde);
等价于
zv.value.ptr = (lde); zv.u1.type_info = IS_PTR;
list_destructors
是一个全局静态HashTable
,资源类型注册时,将一个zval
结构体变量zv
存放入list_destructors
的arData
中,而zv
的value.ptr
却指向了zend_rsrc_list_dtors_entry *lde
,lde
中包含的该种资源释放函数指针、持久资源的释放函数指针,资源类型名称,该资源在 hashtable 中的索引依据 (resource_id
)等。
而这里的resource_id
则是该函数的返回值,所以后面我们在解析该类型变量时,都需要将resource_id
带上。
整个的注册步骤可以总结为下图:
2.2 资源的注册
ZEND_API zend_resource* zend_register_resource(void *rsrc_pointer, int rsrc_type) { zval *zv; zv = zend_list_insert(rsrc_pointer, rsrc_type); return Z_RES_P(zv); }
该函数的功能则是将zend_list_insert
返回的zval
中的资源指针返回。Z_RES_P
宏在Zend/zend_types.h
中定义。
重点分析zend_list_insert
ZEND_API zval *zend_list_insert(void *ptr, int type) { int index; zval zv; index = zend_hash_next_free_element(&EG(regular_list)); if (index == 0) { index = 1; } ZVAL_NEW_RES(&zv, index, ptr, type); return zend_hash_index_add_new(&EG(regular_list), index, &zv); }
其中zend_hash_next_free_element
宏,返回&EG(regular_list)
表的nNextFreeElement
,后面用来作为索引查询的依据。
而ZVAL_NEW_RES
宏是 PHP 7 新增的一套东西,把一个资源装载到zval
里去,因为PHP 7 中Bucket
只能存zval
了。
#define ZVAL_NEW_RES(z, h, p, t) do { \ zend_resource *_res = \ (zend_resource *) emalloc(sizeof(zend_resource)); \ zval *__z; \ GC_REFCOUNT(_res) = 1; \ GC_TYPE_INFO(_res) = IS_RESOURCE; \ _res->handle = (h); \ _res->type = (t); \ _res->ptr = (p); \ __z = (z); \ Z_RES_P(__z) = _res; \ Z_TYPE_INFO_P(__z) = IS_RESOURCE_EX; \ } while (0)
代码比较清晰,首先根据h
,p
,t
新建了一个资源,然后一起存入了z
这个zval的结构体。(最后两个宏前面刚刚讨论过了)
最后就是zend_hash_index_add_new
宏了,追踪代码发现其最后等价于调用的是
_zend_hash_index_add_or_update_i(&EG(regular_list), index, &zv, HASH_ADD | HASH_ADD_NEW ZEND_FILE_LINE_RELAY_CC)
关于HashTable
的具体操作,这里暂不做细致的分析,后面单独再单独说。
2.3 解析资源源码分析
ZEND_API void *zend_fetch_resource(zend_resource *res, const char *resource_type_name, int resource_type) { if (resource_type == res->type) { return res->ptr; } if (resource_type_name) { const char *space; const char *class_name = get_active_class_name(&space); zend_error(E_WARNING, "%s%s%s(): supplied resource is not a valid %s resource", class_name, space, get_active_function_name(), resource_type_name); } return NULL; }
在上面的例子中我们是这样解析的
(FILE *)zend_fetch_resource(Z_RES_P(filehandle), TIPI_FILE_TYPE, le_tipi_file)
首先通过Z_RES_P
宏,获取filehandle
这个zval
变量中的zend_resource
。然后zend_fetch_resource
中只是对比了zend_resource
的type
与我们预想的资源类型是否一致,然后返回了zend_resource
的*ptr
,最后转换成FILE *
指针。
PHP7 中资源的解析比 PHP5中解析简单快捷很多,得益于其 zval 结构的改变。
原来PHP5中则需要通过EG(regular_list)
查找,如下图所示。
而现在 PHP7的解析则直接从zval
里解析出zend_resource
,如下图所示:
2.4 删除资源源码分析
ZEND_API int zend_list_close(zend_resource *res) { if (GC_REFCOUNT(res) <= 0) { return zend_list_free(res); } else if (res->type >= 0) { zend_resource_dtor(res); } return SUCCESS; }
与PHP5 不同的地方,这里不是每次都进来将其引用计数减一操作,而是直接调用zend_resource_dtor
函数。
static void zend_resource_dtor(zend_resource *res) { zend_rsrc_list_dtors_entry *ld; zend_resource r = *res; res->type = -1; res->ptr = NULL; ld = zend_hash_index_find_ptr(&list_destructors, r.type); if (ld) { if (ld->list_dtor_ex) { ld->list_dtor_ex(&r); } } else { zend_error(E_WARNING, "Unknown list entry type (%d)", r.type); } }
如果引用计数已经等于0或者小于0了,那么才从EG(regular_list)
中删除
ZEND_API int zend_list_free(zend_resource *res) { if (GC_REFCOUNT(res) <= 0) { return zend_hash_index_del(&EG(regular_list), res->handle); } else { return SUCCESS; } }
原理图还是引用上面的注册资源类型、并注册资源的图:
先从zend_resource
逆向通过其type
在list_destructors
中索引层层关联,找到该类资源的释放回调函数,然后对该资源执行释放回调函数。
而后面的从EG(regular_list)
中删除,则是通过res->handler
做为索引的依据。