PHP内核介绍及扩展开发指南—Extensions 的编写

转载地址：   http://stblog.baidu-tech.com/?p=601

Extensions 的编写

理解了这些运行机制以后，本章着手介绍Extensions 的编写，但凡写程序的人都知道hello world，那好，就从hello world开始。

1.1Hello World

这是摘自《PHP手册》的示例程序：

01 /* include standard header */
02 #include "php.h"
03
04 /* declaration of functions to be exported */
05 ZEND_FUNCTION(first_module);
06
07 /* compiled function list so Zend knows what's in this module */
08 zend_function_entry firstmod_functions[] =
09 {
10    ZEND_FE(first_module, NULL)
11    {NULL, NULL, NULL}
12 };
13
14 /* compiled module information */
15 zend_module_entry firstmod_module_entry =
16 {
17    STANDARD_MODULE_HEADER,
18    "First Module",
19    firstmod_functions,
20    NULL,
21    NULL,
22    NULL,
23    NULL,
24    NULL,
25    NO_VERSION_YET,
26    STANDARD_MODULE_PROPERTIES
27 };
28
29 /* implement standard "stub" routine to introduce ourselves to Zend */
30 #if COMPILE_DL_FIRST_MODULE
31 ZEND_GET_MODULE(firstmod)
32 #endif
33
34 /* implement function that is meant to be made available to PHP */
35 ZEND_FUNCTION(first_module)
36 {
37    long parameter;
38    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", ¶meter)
39 == FAILURE)
40 return;
41 RETURN_LONG(parameter);
42 }

这段代码实现了一个简单的extension，首先它包含了“php.h”，这是所有extensions都需要包含的头文件，它定义、声明了我们可以访问的所有Zend数据结构、常量和API等。下面对剩余的步骤进行解释。

1.1.1  声明导出函数

1 ZEND_FUNCTION(first_module);

ZEND_FUNCTION宏用于声明一个可在PHP代码中调用的函数，其参数即成为PHP函数名，因此，这一句声明了一个名为first_module的PHP函数，将其展开如下：

01 void zif_first_module (INTERNAL_FUNCTION_PARAMETERS);
02
03 // 最终展开得：
04 void zif_first_module (
05 int ht,
06 zval * return_value,
07 zval **return_value_ptr,
08 zval * this_ptr,
09 int return_value_used
10 );

可见，ZEND_FUNCTION就是简单的声明了一个名为zif_ first_module的C函数，zif可能是”Zend Internal Function”的缩写。函数的原型满足Zend引擎对PHP函数的调用约定，关于其参数将在后面章节进行解释。

1.1.2  声明导出函数块

声明C函数后，Zend并不知道如何调用，我们需要使用如下的语句来完成C函数到PHP函数的映射：

1 zend_function_entry firstmod_functions[] =
2 {
3 ZEND_FE(first_module, NULL)
4 {NULL, NULL, NULL}
5 };

这创建了一个zend_function_entry数组，zend_function_entry存储了关于如何调用该PHP函数的信息，通过它Zend引擎就能够理解和调用我们的函数。

其定义如下：

1 typedef struct _zend_function_entry {
2     char *fname;
3     void (*handler)(INTERNAL_FUNCTION_PARAMETERS);
4     struct _zend_arg_info *arg_info;
5     zend_uint num_args;
6     zend_uint flags;
7 } zend_function_entry;

fname是PHP函数名，是PHP代码能够通过它来调用我们的函数；handler是指向我们在前面声明的C函数的函数指针。这两个参数已经足以完成从C函数到PHP函数的映射。剩余的参数用于告诉Zend该PHP函数对于函数参数的要求，arg_info是个数组，它的每一项都描述了对应下标的参数，num_args是参数的个数，具体将在后面的章节介绍。

我们可以手动填充一个zend_function_entry，但更好的办法是使用Zend提供的宏ZEND_FE，因为Zend并不保证这个结构以后不会变。ZEND_FE使用第一个参数作为PHP函数名，并且在添加了zif前缀后作为C函数名；第二个参数用于填充arg_info，通常使用NULL。上面的代码将得到这样一个zend_function_entry结构：{” first_module,”, zif_first_module, NULL, 0, 0}。当然，这并不是说PHP函数名必须和C函数名有什么关系，也可以通过宏ZEND_NAMED_FE来手动指定PHP函数名，不过这并不是个好主意。

我们必须为希望导出的每一个C函数都创建一个zend_function_entry结构，并将其放到一个数组中以备后用，数组最后一项的成员必须全部为NULL，这用于标记数组的结束。

1.1.3  填写模块信息

下一步需要将我们的模块介绍给Zend，主要包括我们的模块名和导出的函数，这通过填充一个zend_module_entry结构来完成。

zend_module_entry firstmod_module_entry =
{
   STANDARD_MODULE_HEADER,
   "First Module",
   firstmod_functions,
   NULL,
   NULL,
   NULL,
   NULL,
   NULL,
   NO_VERSION_YET,
   STANDARD_MODULE_PROPERTIES
};

STANDARD_MODULE_HEADER和STANDARD_MODULE_
PROPERTIES宏填充了该结构的首尾部分，具体填充了什么并不是我们需要关心的，并且为了兼容后续版本也最好不要手工修改。

第二、三项是模块名称和导出函数，名称可以任意填写，导出函数就是我们在前面准备好的zend_function_entry数组。

接下来的五个参数是函数指针，其用法在后面介绍，这里只用NULL填充。

下面的参数是一个C字符串，用于表示模块版本，如果没有则使用NO_VERSION_YET，其实就是NULL。

填写完毕后，需要把这个结构传给Zend引擎，这通过下面的语句完成：

1 #if COMPILE_DL_FIRST_MODULE
2 ZEND_GET_MODULE(firstmod)
3 #endif

宏开关用于判断是否是动态链接的，动态链接时才会执行下面的语句，本文仅介绍动态链接的模块，并不关心静态链接时如何与Zend交流信息，因此，可以认为条件总为真。
ZEND_GET_MODULE(firstmod)最后展开得到名为get_module的一个函数：

1 zend_module_entry *get_module(void)
2 {
3 return &firstmod_module_entry;
4 }

这个函数就是简单的返回我们填充的zend_module_entry结构，这里需要注意的是结构的名称必须是xxx_module_entry，xxx是传递给ZEND_GET_MODULE的参数。当Zend加载我们的模块时，它首先会解析并调用名为get_module的函数，这样就可以得到我们的zend_module_entry，于是，PHP代码就可以调用模块导出的函数了。

1.1.4 实现导出函数

代码最后一部分实现了我们导出的函数：

1 ZEND_FUNCTION(first_module)
2 {
3 long parameter;
4 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l",
5 ¶meter) == FAILURE)
6 return;
7 RETURN_LONG(parameter);
8 }

这里依然要用ZEND_FUNCTION来声明函数原型，函数体通过Zend API和宏，访问了函数参数并返回一个long值——这些都将在后面的章节进行详细介绍。

1.2使用参数

函数的一个重要部分就是访问参数，但由于extension的特殊性，我们无法像通常的函数那样来访问参数。

先来看导出C函数的原型：

1 void zif_first_module (
2 int ht,
3 zval * return_value,
4 zval **return_value_ptr,
5 zval * this_ptr,
6 int return_value_used
7 );

ht是用户传入参数的数目，但一般不应直接读取，而是通过宏ZEND_NUM_ARGS()来获取，这通常用于判断用户是否传入了规定数目的参数。下面介绍如何在我们的C函数中访问这些参数。

1.2.1  标准方法

常用的方法是使用下面这个函数，其使用方法类似于scanf，采用格式化字符串和变长参数列表的方式：

1 int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);

num_args指出我希望获取的参数数目，通常使用ZEND_NUM_ARGS()，因为我们一般会先用ZEND_NUM_ARGS()判断用户是否传入了规定数目的参数。TSRMLS_DC宏用于线程安全，define和declare时必须这样填写，在调用时应该改用TSRMLS_CC。

type_spec是格式化字符串，其每个字符代表期望的当前参数的类型，之后应传递相应类型变量的指针来接收值，就像scanf那样，可用的字符如下：

格式字符	PHP参数类型	接收变量类型
l	long	long
d	double	double
s	string	char*和int
b	boolean	zend_bool
r	resource	zval*
a	array	zval*
z	zval	zval*
o/O/C	类，不予讨论	N/A

这里面，string是个特例，它需要两个参数，分别获取字符串指针和长度，这是因为PHP没有采用C串，不能根据0来判断字符串结尾。下面是个示例程序：

01 // 获取一个long、一个string和一个resource
02 long l;
03 char *s;        // 字符串地址
04 int s_len;      // 字符串长度
05 zval *res;
06
07 // 检查参数数目
08 if(ZEND_NUM_ARGS() != 3)
09 WRONG_PARAM_COUNT; // 该宏输出相应错误信息并退出当前函数
10
11 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
12                          "lsr", &l, &s, &s_len, &res) == FAILURE)
13  return;

由于PHP语法不能规定函数原型，因此用户可以传递任意类型的参数，对此，zend_parse_parameters自动进行了类型检查和转换：在内置标量类型，即long、double、boolean和string之间，Zend会自动进行类型转换，我们总能成功取得参数；resource和array则不进行转换，用户传入的参数必须具有指定类型，否则返回错误；zval作为通用结构，可以用于任何参数类型，Zend只需要简单的将其写入本地的接收变量。

除了类型格式符外，该函数还支持另外3个控制符：

格式字符	意义
|	后面的参数是可选的，如果用户没有传递相应的参数，则本地接收变量保持不变，这用于支持默认参数；
!	前面的那个参数可以是NULL，仅用于razoOC，如果用户传递的是NULL，则本地的接收zval*被设为NULL；
/	如果前面那个参数不是引用传递的，则不直接使用传入的zval，而是执行Copy-On-Write。这一点将在后面解释。

最后，关于参数的数目也是有要求的。如果没有采用默认参数，即’|’格式符，则ZEND_NUM_ARGS()、num_args和格式串指出的参数数目这三者间必须完全匹配，否则zend_parse_parameters返回错误；如果使用了默认参数，则ZEND_NUM_ARGS()应和num_args相等，并且应该落在格式串指出的参数数目区间内。

1.2.2 底层方法

大部分情况下，使用标准方法就可以了，但有些函数可能需要处理变参，标准方法对此无能为力(*)。此时，只有使用更加原始的方法——直接获取zval。Zend提供了如下的API：

1 int zend_get_parameters_array_ex(
2 int param_count,
3 zval ***argument_array
4 TSRMLS_DC);

param_count是希望获取的参数数目，这个值不得大于ZEND_NUM_ARGS()，否则函数出错。argument_array是一个zval**类型的数组，用于接收参数。
这个函数只是简单的返回zval，为了使用它们，我们需要自己访问其成员。首先是获取参数类型，这可以通过zval.type值来判断，可用的type见1.1.1节。之后是获取该type对应的值，我们可以直接访问zval的成员，比如zval.value.lval就是long值，但更方便的方法是使用Zend提供的宏：

宏	展开
Z_LVAL(zval)	(zval).value.lval
Z_DVAL(zval)	(zval).value.dval
Z_STRVAL(zval)	(zval).value.str.val
Z_STRLEN(zval)	(zval).value.str.len
Z_ARRVAL(zval)	(zval).value.ht
Z_RESVAL(zval)	(zval).value.lval
Z_OBJVAL(zval)	(zval).value.obj
Z_BVAL (zval)	((zend_bool)(zval).value.lval)
Z_TYPE(zval)	(zval).type

一个比较特殊的宏是Z_BVAL，它不是简单的返回值，而是进行了类型转换。另外，这些宏都有相应的xxx_P和xxx_PP版本，用于访问zval*和zval**。

有时，用户传入参数的类型并不是我们期望的，这就需要手动进行类型转换了。为此，Zend提供了如下几个函数：

convert_to_boolean_ex()

convert_to_long_ex()

convert_to_double_ex()

convert_to_string_ex()

convert_to_array_ex()

convert_to_object_ex()

convert_to_null_ex()

这些函数可将目标zval转换成指定类型，它接收zval**作为参数，为什么不用zval*呢？这是因为，这些函数有一个额外的步骤，它如果发现传入的zval不是引用类型的，并且需要执行类型转换，则会首先执行Copy-On-Write，并对副本施行转换，因此，为了返回副本必须使用zval**作为参数。如果zval是引用型的，则转换直接作用于目标zval结构。

如果无法转换，这些函数就会将zval设置为目标类型的虚值，比如0、FALSE、空串等，因此函数总会成功返回。

这些函数的非ex版本不执行zval分离，而是直接作用于原zval,因此参数类型是zval*。

1.2.2  引用传递

函数参数的传递也是采用的引用计数方式，函数栈中存放的只是zval**，它很可能和几个变量共享一个zval。

显然，对于引用型的zval，我们可以直接进行写入操作；而对于非引用型的zval，并且其refcount大于1时，如果要进行写入操作，就必须执行zval分离（参见1.1.3）。refcount等于1的情况是因为Zend引擎已经执行了zval状态切换（参见1.1.4情况II），我们得到的是自己独占的zval，可以直接写入。

关于传入的zval是否引用，可以通过zval.is_ref来判断，或者使用宏PZVAL_IS_REF(zval*)。对于zval分离，可以使用宏SEPARATE_ZVAL(zval**)，它会自动判断refcount，并且将新zval的地址填充到参数里。

1.2.4  编译检查(TODO)

上面几节介绍了如何在我们的函数中对参数进行检查，也就是运行时检查，这为函数的编写带来了一些负担，代码也不够简洁。为此，Zend提供了编译时检查机制，允许我们指定函数原型，如果用户不按规定调用，则会报错并且跳过该函数，因此，我们的函数总能得到期望的参数。

1.3返回值

从C函数向PHP返回值，并不能使用通常的return语句，导出函数的原型也说明了这一点：

1 void zif_first_module (
2 int ht,
3 zval * return_value,
4 zval **return_value_ptr,
5 zval * this_ptr,
6 int return_value_used
7 );

因此，Zend将返回值地址作为参数传给我们，return_value是Zend为我们预先创建的一个标准zval结构，相当于一个局部变量，用户获得返回值时就相当于对return_value进行赋值操作，我们只需填充它即可；return_value_used表明用户是否使用了返回值，0表明没有使用返回值，当函数结束后return_value的refcount将被减为0，并被销毁，因此，这种情况下完全可以不处理返回值；return_value_ptr用于返回引用，它需要和zend_function_entry.arg_info联合使用，通常都是NULL。

Zend提供了一组宏用于填充return_value：

Macro	Description
RETURN_RESOURCE(resource)	resource
RETURN_BOOL(bool)	boolean
RETURN_FALSE	false
RETURN_TRUE	true
RETURN_NULL()	NULL