(八)故障处理

实际上,在对静态或动态模块进行编译时没有太多故障处理工作要做。唯一可能的问题就是编译器会警告说找不到某些定义或者类似的事情。如果出现这种情况,你应该确认一下所有的头文件都是可用的并且它们的路径都已经在编译命令中被指定。为了确保每个文件都能被正确地定位,你可以先提取一个干净的 PHP 源码树,然后在 Ext 目录使用自动构建工具来创建这些文件。用这种方法就可以确保一个安全的编译环境。假如这样也不行,那就只好试试手动编译了。


PHP 也可能会警告说在你的模块里面有一些未定义的函数。(如果你没有改动样例文件的话这种情况应该不会发生。)假如你在模块中拼错了一些你想访问的外部函数的名字,那么它们就会在符号表中显示为“未能连接的符号”。这样在 PHP 动态加载或连接时,它们就不会运行--在二进制文件中没有相应的符号。为了解决这个问题,你可以在你的模块文件中找一下错误的声明或外部引用。注意,这个问题仅仅发生在动态可加载模块身上。而在静态模块身上则不会发生,因为静态模块在编译时就会抛出这些错误。


(九)关于模块代码的讨论

OK,现在你已经有了一个安全的构建环境,也可以把模块编译进 PHP 了。那么,现在就让我们开始详细讨论一下这里面究竟是如何工作的吧~


模块结构

所有的 PHP 模块通常都包含以下几个部分:

包含头文件(引入所需要的宏、API定义等);

声明导出函数(用于 Zend 函数块的声明);

声明 Zend 函数块;

声明 Zend 模块;

实现 get_module() 函数;

实现导出函数。


包含头文件

模块所必须包含的头文件仅有一个 php.h,它位于 main 目录下。这个文件包含了构建模块时所必需的各种宏和API 定义。


小提示: 

专门为模块创建一个含有其特有信息的头文件是一个很好的习惯。这个头文件应该包含 php.h 和所有导出函数的定义。如果你是使用 ext_skel 来创建模块的话,那么你可能已经有了这个文件,因为这个文件会被 ext_skel 自动生成。


声明导出函数

为了声明导出函数(也就是让其成为可以被 PHP 脚本直接调用的原生函数),Zend 提供了一个宏来帮助完成这样一个声明。代码如下:

ZEND_FUNCTION ( my_function );

ZEND_FUNCTION 声明了一个使用 Zend 内部 API 来编译的新的C 函数。这个 C 函数是 void 类型,以 INTERNAL_FUNCTION_PARAMETERS (这是另一个宏)为参数,而且函数名字以 zif_ 为前缀。把上面这句声明展开可以得到这样的代码:

voidzif_my_function ( INTERNAL_FUNCTION_PARAMETERS );

接着再把 INTERNAL_FUNCTION_PARAMETERS 展开就会得到这样一个结果:

void zif_my_function(   
	int ht,   
	zval * return_value,   
	zval * this_ptr,   
	int return_value_used,   
	zend_executor_globals * executor_globals
);

在解释器(interpreter)和执行器(executor)被分离出PHP 包后,这里面(指的是解释器和执行器)原有的一些 API 定义及宏也渐渐演变成了一套新的 API 系统:Zend API。如今的 Zend API 已经承担了很多原来(指的是分离之前)本属于 PHP API 的职责,大量的 PHP API 被以别名的方式简化为对应的 Zend API。我们推荐您应该尽可能地使用 Zend API,PHP API 只是因为兼容性原因才被保留下来。举例来说, zval 和 pval 其实是同一类型,只不过 zval 定义在 Zend 部分,而 pval 定义在 PHP 部分(实际上 pval 根本就是 <code>zval 的一个别名)。但由于 INTERNAL_FUNCTION_PARAMETERS 是一个 Zend 宏,因此我们在上面的声明中使用了 zval 。在编写代码时,你也应该总是使用 zval 以遵循新的 Zend API 规范。


这个声明中的参数列表非常重要,你应该牢记于心。(下表3.1“PHP 调用函数的 Zend 参数”详细介绍了这些参数)

参数说明
ht这个参数包含了Zend 参数的个数。但你不应该直接访问这个值,而是应该通过 ZEND_NUM_ARGS() 宏来获取参数的个数。
return_value这个参数用来保存函数向 PHP 返回的值。访问这个变量的最佳方式也是用一系列的宏。后面我们会有详细说明。
this_ptr根据这个参数你可以访问该函数所在的对象(换句话说,此时这个函数应该是一个类的“方法”)。推荐使用函数 getThis() 来得到这个值。
return_value_used这个值主要用来标识函数的返回值是否为脚本所使用。0 表示脚本不使用其返回值,而 1 则相反。通常用于检验函数是否被正确调用以及速度优化方面,这是因为返回一个值是一种代价很昂贵的操作(可以在 array.c 里面看一下是如何利用这一特性的)。
executor_globals这个变量指向 Zend Engine 的全局设置,在创建新变量时这个这个值会很有用。我们也可以函数中使用宏 TSRMLS_FETCH() 来引用这个值。

声明 Zend 函数块

现在你已经声明了导出函数,除此之外你还必须得将其引入 Zend 。这些函数的引入是通过一个包含有 N 个 zend_function_entry 结构的数组来完成的。数组的每一项都对应于一个外部可见的函数,每一项都包含了某个函数在 PHP 中出现的名字以及在 C 代码中所定义的名字。zend_function_entry 的内部定义如“例3.4 zend_function_entry 的内部声明”所示:


例3.4 zend_function_entry 的内部声明

typedef struct _zend_function_entry {   
	char *fname;   
	void (*handler)(INTERNAL_FUNCTION_PARAMETERS);   
	unsigned char *func_arg_types;   
} zend_function_entry
字段说明
fname指定在 PHP 里所见到的函数名(比如:fopen、mysql_connect 或者是我们样例中的 first_module)。
handler指向对应 C 函数的句柄。样例可以参考前面使用宏INTERNAL_FUNCTION_PARAMETERS 的函数声明。
func_arg_types用来标识一些参数是否要强制性地按引用方式进行传递。通常应将其设定为 NULL。

对于上面的例子,我们可以这样来声明:

zend_function_entryfirstmod_functions[] =
{
    ZEND_FE(first_module, NULL)
    {NULL, NULL, NULL}
};

你可能已经看到了,这个结构的最后一项是 {NULL, NULL, NULL} 。事实上,这个结构的最后一项也必须始终是 {NULL, NULL, NULL},因为 Zend Engine 需要靠它来确认这些导出函数的列表是否列举完毕。


注意:

你不应该使用一个预定义的宏来代替列表的结尾部分(即{NULL, NULL, NULL}),因为编译器会尽量寻找一个名为 NULL 的函数的指针来代替 NULL !


宏 ZEND_FE(Zend Function Entry的简写)将简单地展开为一个 zend_function_entry 结构。不过需要注意,这些宏对函数采取了一种很特别的命名机制:把你的C函数前加上一个 zif_ 前缀。比方说,ZEND_FE(first_module) 其实是指向了一个名为 zif_first_module() 的 C 函数。如果你想把宏和一个手工编码的函数名混合使用时(这并不是一个好的习惯),请你务必注意这一点。


小提示:

如果出现了一些引用某个名为 zif_*() 函数的编译错误,那十有八九与 ZEND_FE 所定义的函数有关。


“表 3.2 可用来定义函数的宏”给出了一个可以用来定义一个函数的所有宏的列表:


表3.2 可用来定义函数的宏

说明
ZEND_FE(name, arg_types)定义了一个zend_function_entry 内字段name为 “name” 的函数。arg_types 应该被设定为 NULL。这个声明需要有一个对应的 C 函数,该这个函数的名称将自动以 zif_ 为前缀。举例来说, ZEND_FE(“first_module”, NULL) 就引入了一个名为 first_module() 的 PHP 函数,并被关联到一个名为 zif_first_module() 的C函数。这个声明通常与 ZEND_FUNCTION 搭配使用。
ZEND_NAMED_FE(php_name, name, arg_types)定义了一个名为 php_name 的 PHP 函数,并且被关联到一个名为 name 的 C 函数。arg_types 应该被设定为 NULL。 如果你不想使用宏 ZEND_FE 自动创建带有 zif_ 前缀的函数名的话可以用这个来代替。通常与 ZEND_NAMED_FUNCTION搭配使用。
ZEND_FALIAS(name, alias, arg_types)为 name 创建一个名为 alias 的别名。arg_types 应该被设定为 NULL。这个声明不需要有一个对应的 C 函数,因为它仅仅是创建了一个用来代替 name 的别名而已。
PHP_FE(name, arg_types)以前的 PHP API,等同于 ZEND_FE 。仅为兼容性而保留,请尽量避免使用。
PHP_NAMED_FE(runtime_name, name, arg_types)以前的 PHP API,等同于ZEND_NAMED_FE 。仅为兼容性而保留,请尽量避免使用。


注意:

你不能将 ZEND_FE 和 PHP_FUNCTION 混合使用,也不能将 PHP_FE 和 ZEND_FUNCTION 混合使用。但是将 ZEND_FE + ZEND_FUNCTION 和 PHP_FE + PHP_FUNCTION 一起混合使用是没有任何问题的。当然我们并不推荐这样的混合使用,而是建议你全部使用 ZEND_* 系列的宏。


声明 Zend 模块

Zend 模块的信息被保存在一个名为zend_module_entry 的结构,它包含了所有需要向 Zend 提供的模块信息。你可以在“例 3.5 zend_module_entry 的内部声明”中看到这个 Zend 模块的内部定义:


例3.5 zend_module_entry 的内部声明

typedef struct _zend_module_entry zend_module_entry; 
struct _zend_module_entry {  
	unsigned short size;  
	int zend_api;  
	unsigned char zend_debug;  
	unsigned char zts;  
	char *name;  
	zend_function_entry *functions;  
	int (*module_startup_func)(INIT_FUNC_ARGS);  
	int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);  
	int (*request_startup_func)(INIT_FUNC_ARGS);  
	int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);  
	void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);  
	char *version; 
	// 其余的一些我们不感兴趣的信息  
};
字段说明

size, zend_api

zend_debug and zts

通常用 “STANDARD_MODULE_HEADER” 来填充,它指定了模块的四个成员:标识整个模块结构大小的 size ,值为 ZEND_MODULE_API_NO 常量的 zend_api,标识是否为调试版本(使用 ZEND_DEBUG 进行编译)的 zend_debug,还有一个用来标识是否启用了 ZTS (Zend 线程安全,使用 ZTS 或 USING_ZTS 进行编译)的 zts。
name模块名称 (像“File functions”、“Socket functions”、“Crypt”等等). 这个名字就是使用 phpinfo() 函数后在“Additional Modules”部分所显示的名称。
functionsZend 函数块的指针, 这个我们在前面已经讨论过。
module_startup_func模块启动函数。这个函数仅在模块初始化时被调用,通常用于一些与整个模块相关初始化的工作(比如申请初始化的内存等等)。如果想表明模块函数调用失败或请求初始化失败请返回 FAILURE,否则请返回 SUCCESS。可以通过宏 ZEND_MINIT 来声明一个模块启动函数。如果不想使用,请将其设定为 NULL。
module_shutdown_func模块关闭函数。这个函数仅在模块卸载时被调用,通常用于一些与模块相关的反初始化的工作(比如释放已申请的内存等等)。这个函数和 module_startup_func() 相对应。如果想表明函数调用失败或请求初始化失败请返回 FAILURE,否则请返回 SUCCESS。可以通过宏ZEND_MSHUTDOWN 来声明一个模块关闭函数。如果不想使用,请将其设定为 NULL。
request_startup_func请求启动函数。这个函数在每次有页面的请求时被调用,通常用于与该请求相关的的初始化工作。如果想表明函数调用失败或请求初始化失败请返回 FAILURE,否则请返回 SUCCESS。注意: 如果该模块是在一个页面请求中被动态加载的,那么这个模块的请求启动函数将晚于模块启动函数的调用(其实这两个初始化事件是同时发生的)。可以使用宏 ZEND_RINIT 来声明一个请求启动函数,若不想使用,请将其设定为 NULL。
request_shutdown_func请求关闭函数。这个函数在每次页面请求处理完毕后被调用,正好与 request_startup_func() 相对应。如果想表明函数调用失败或请求初始化失败请返回 FAILURE,否则请返回 SUCCESS。注意: 当在页面请求作为动态模块加载时, 这个请求关闭函数先于模块关闭函数的调用(其实这两个反初始化事件是同时发生的)。可以使用宏 ZEND_RSHUTDOWN 来声明这个函数,若不想使用,请将其设定为 NULL 。
info_func模块信息函数。当脚本调用 phpinfo() 函数时,Zend 便会遍历所有已加载的模块,并调用它们的这个函数。每个模块都有机会输出自己的信息。通常情况下这个函数被用来显示一些环境变量或静态信息。可以使用宏 ZEND_MINFO 来声明这个函数,若不想使用,请将其设定为 NULL 。
version模块的版本号。如果你暂时还不想给某块设置一个版本号的话,你可以将其设定为 NO_VERSION_YET。但我们还是推荐您在此添加一个字符串作为其版本号。版本号通常是类似这样: “2.5-dev”, “2.5RC1”, “2.5” 或者 “2.5pl3” 等等。
Remaining structure elements这些字段通常是在模块内部使用的,通常使用宏STANDARD_MODULE_PROPERTIES 来填充。而且你也不应该将他们设定别的值。STANDARD_MODULE_PROPERTIES_EX 通常只会在你使用了全局启动函数(ZEND_GINIT)和全局关闭函数(ZEND_GSHUTDOWN)时才用到,一般情况请直接使用 STANDARD_MODULE_PROPERTIES 。

在我们的例子当中,这个结构被定义如下:

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

这基本上是你可以设定最简单、最小的一组值。该模块名称为“First Module”,然后是所引用的函数列表,其后所有的启动和关闭函数都没有使用,均被设定为了 NULL。


作为参考,你可以在表 3.3 “所有可声明模块启动和关闭函数的宏”中找到所有的可设置启动与关闭函数的宏。这些宏暂时在我们的例子中还尚未用到,但稍后我们将会示范其用法。你应该使用这些宏来声明启动和关闭函数,因为它们都需要引入一些特殊的变量( INIT_FUNC_ARGS 和 SHUTDOWN_FUNC_ARGS ),而这两个参数宏将在你使用下面这些预定义宏时被自动引入(其实就是图个方便)。如果你是手工声明的函数或是对函数的参数列表作了一些必要的修改,那么你就应该修改你的模块相应的源代码来保持兼容。


表3.3 所有可声明模块启动和关闭函数的宏

描述
ZEND_MINIT(module)声明一个模块的启动函数。函数名被自动设定为zend_minit_<module> (比如:zend_minit_first_module)。通常与ZEND_MINIT_FUNCTION 搭配使用。
ZEND_MSHUTDOWN(module)声明一个模块的关闭函数。函数名被自动设定为zend_mshutdown_<module> (比如:zend_mshutdown_first_module)。通常与ZEND_MSHUTDOWN_FUNCTION搭配使用。
ZEND_RINIT(module)声明一个请求的启动函数。函数名被自动设定为zend_rinit_<module> (比如:zend_rinit_first_module)。通常与ZEND_RINIT_FUNCTION搭配使用。
ZEND_RSHUTDOWN(module)声明一个请求的关闭函数。函数名被自动设定为zend_rshutdown_<module> (比如:zend_rshutdown_first_module)。通常与ZEND_RSHUTDOWN_FUNCTION 搭配使用。
ZEND_MINFO(module)声明一个输出模块信息的函数,用于 phpinfo()。函数名被自动设定为zend_info_<module> (比如:zend_info_first_module)。通常与 ZEND_MINFO_FUNCTION 搭配使用。

实现 get_module() 函数

这个函数只用于动态可加载模块。我们先来看一下如何通过宏 ZEND_GET_MODULE 来创建这个函数:

#if COMPILE_DL_FIRSTMOD
ZEND_GET_MODULE(firstmod)
#endif

这个函数的实现被一条件编译语句所包围。这是很有必要的,因为 get_module() 函数仅仅在你的模块想要编译成动态模块时才会被调用。通过在编译命令行指定编译条件:COMPILE_DL_FIRSTMOD (也就是上面我们设置的那个预定义)的打开与否,你就可以决定是编译成一个动态模块还是编译成一个内建模块。如果想要编译成内建模块的话,那么这个 get_module() 将被移除。


get_module() 函数在模块加载时被 Zend 所调用,你也可以认为是被你 PHP 脚本中的 dl() 函数所调用。这个函数的作用就是把模块的信息信息块传递 Zend 并通知 Zend 获取这个模块的相关内容。


如果你没有在一个动态可加载模块中实现 get_module() 函数,那么当你在访问它的时候 Zend 就会向你抛出一个错误信息。


实现导出函数

导出函数的实现是我们构建扩展的最后一步。在我们的 first_module 例子中,函数被实现如下:

ZEND_FUNCTION(first_module)   {   
	long parameter;   
	if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &para meter) == FAILURE) {   
		return;   
	}   
	RETURN_LONG(parameter) ;   
}

这个函数是用宏 ZEND_FUNCTION 来声明的,和前面我们讨论的 Zend 函数块中的 ZEND_FE 声明相对应。在函数的声明之后,我们的代码便开始检查和接收这个函数的参数。在将参数进行转换后将其值返回。(参数的接收和处理我们马上会在下一节中讲到)。


小结

一切基本上就这样了 ―― 我们在实现一个模块时不会再遇到其他方面的事了。内建模块也基本上同动态模块差不多。因此,有了前面几节我们所掌握的信息,再在你遇到 PHP 源代码的时候你就有能力去搞定这些小麻烦。


在下面的几个小节里,我们将会学习到如何利用 PHP 内核来创建一个更为强大的扩展!


(十)接收参数

对于扩展来说,最重要的一件事就是如何接收和处理那些通过函数参数传递而来的数据。大多数扩展都是用来处理某些特定的输入数据(或者是根据参数来决定进行某些特定的动作),而函数的参数则是 PHP 代码层和 C 代码层之间交换数据的唯一途径。当然,你也可以通过事先定义好的全局变量来交换数据(这个我们稍后会谈到),不过这种习惯可不太好,我们应该尽量避免。


在 PHP 中并不需要做任何显式的函数声明,这也就是我们为什么说 PHP 的调用语法是动态的而且 PHP 从不会检查任何错误的原因。调用语法是否正确完全是留给用户自己的工作。也就是说,在调用一个函数时完全有可能这次用一个参数而下次用 4 个参数,而且两种情况在语法上都是正确的。


取得参数数量

因为 PHP 不但没法根据函数的显式声明来对调用进行语法检查,而且它还支持可变参数,所以我们就不得不在所调用函数的内部来获取参数个数。这个工作可以交给宏 ZEND_NUM_ARGS 来完成。在(PHP4)以前,这个宏(在 PHP3 中应该指的是宏 ARG_COUNT,因为 ZEND_NUM_ARGS 宏是直到 PHP 4.0 才出现的,并且其定义一直未变。PHP4 及以后虽也有 ARG_COUNT 宏定义,但却仅仅是为兼容性而保留的,并不推荐使用,译者注)是利用所调用的 C 函数中的变量 ht(就是定义在宏 INTERNAL_FUNCTION_PARAMETERS 里面的那个,HashTable * 类型)来获取参数个数的,而现在变量 ht 就只包含函数的参数个数了(int 类型)。与此同时还定义了一个哑宏:ZEND_NUM_ARGS(直接等于 ht,见 Zend.h)。尽量地采用 ZEND_NUM_ARGS 是个好习惯,因为这样可以保证在函数调用接口上的兼容性。


下面的代码展示了如何检查传入函数的参数个数的正确性:

if(ZEND_NUM_ARGS() != 2)
{
    WRONG_PARAM_COUNT;
}

如果没有为该函数传入两个参数,那么就会退出该函数并且发出一个错误消息。在这段代码中我们使用了一个工具宏:WRONG_PARAM_COUNT,它主要用来抛出一个类似:

"Warning: Wrong parameter count for firstmodule() in /home/www/htdocs/firstmod.php on line 5"

这样的错误信息。


这个宏会主要负责抛出一个默认的错误信息,然后便返回调用者。我们可以在 zend_API.h 中找到它的定义:

ZEND_API voidwrong_param_count(void);
#defineWRONG_PARAM_COUNT { wrong_param_count(); return; }

正如您所见,它调用了一个内部函数 wrong_param_count() ,这个函数会输出一个警告信息。至于如何抛出一个自定义的错误信息,可以参见后面的“打印信息”一节。


取回参数

对传入的参数进行解析是一件很常见同时也是颇为乏味的事情,而且同时你还得做好标准化的错误检查和发送错误消息等琐事。不过从 PHP 4.1.0 开始,我们就可以用一个新的参数解析 API 来搞定这些事情。这个 API 可以大大简化参数的接收处理工作,尽管它在处理可变参数时还有点弱。但既然绝大部分函数都没有可变参数,那么使用这个 API 也就理所应当地成为了我们处理函数参数时的标准方法。


这个用于参数解析的函数的原型大致如下:

intzend_parse_parameters(intnum_args TSRMLS_DC, char *type_spec, ...);

第一个参数 num_args 表明了我们想要接收的参数个数,我们经常使用 ZEND_NUM_ARGS() 来表示对传入的参数“有多少要多少”。第二参数应该总是宏 TSRMLS_CC 。第三个参数 type_spec 是一个字符串,用来指定我们所期待接收的各个参数的类型,有点类似于 printf 中指定输出格式的那个格式化字符串。剩下的参数就是我们用来接收 PHP 参数值的变量的指针。


zend_parse_parameters() 在解析参数的同时会尽可能地转换参数类型,这样就可以确保我们总是能得到所期望的类型的变量。任何一种标量类型都可以转换为另外一种标量类型,但是不能在标量类型与复杂类型(比如数组、对象和资源等)之间进行转换。


如果成功地解析和接收到了参数并且在转换期间也没出现错误,那么这个函数就会返回 SUCCESS,否则返回 FAILURE。如果这个函数不能接收到所预期的参数个数或者不能成功转换参数类型时就会抛出一些类似下面这样的错误信息:

Warning - ini_get_all() requires at most 1 parameter, 2 given

Warning - wddx_deserialize() expects parameter 1 to be string, array given

当然,每个错误信息都会带有错误发生时所在的文件名和行数的。


下面这份清单完整地列举出了我们可以指定接收的参数类型:

l - 长整数
d - 双精度浮点数
s - 字符串 (也可能是空字节)和其长度
b - 布尔值
r - 资源, 保存在 zval*
a - 数组, 保存在 zval*
o - (任何类的)对象, 保存在 zval*
O - (由class entry 指定的类的)对象, 保存在 zval*
z - 实际的 zval*


下面的一些字符在类型说明字符串(就是那个 char *type_spec)中具有特别的含义:

|     - 表明剩下的参数都是可选参数。如果用户没有传进来这些参数值,那么这些值就会被初始化成默认值。
/     - 表明参数解析函数将会对剩下的参数以 SEPARATE_ZVAL_IF_NOT_REF() 的方式来提供这个参数的一份拷
        贝,除非这些参数是一个引用。
!     - 表明剩下的参数允许被设定为 NULL(仅用在 a、o、O、r和z身上)。如果用户传进来了一个 NULL 值,
        则存储该参数的变量将会设置为 NULL。

当然啦,熟悉这个函数的最好的方法就是举个例子来说明。下面我们就来看一个例子:

/* 取得一个长整数,一个字符串和它的长度,再取得一个 zval 值。 */   
long l;   
char *s;   
int s_len;  
zval *param;   
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz", &l, &s, &s_len, &param) == FAILURE) {   
	return;   
}   
/* 取得一个由 my_ce 所指定的类的一个对象,另外再取得一个可选的双精度的浮点数。 */   
zval *obj;   
double d = 0.5;   
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d", &ob j, my_ce, &d) == FAILURE) {   
	return;   
}   
/* 取得一个对象或空值,再取得一个数组。如果传递进 来一个空对象,则 obj 将被设置为 NULL。*/   
zval *obj;   
zval *arr;   
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &ob j, &arr) == FAILURE) {   
	return;   
}   
/* 取得一个分离过的数组。*/   
zval *arr;   
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &arr ) == FAILURE) {   
	return;   
}   
/* 仅取得前 3 个参数(这对可变参数的函数很有用)。*/   
zval *z;   
zend_bool b;   
zval *r;   
if (zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE) {   
	return;   
}

注意,在最后的一个例子中,我们直接用了数值 3 而不是 ZEND_NUM_ARGS() 来作为想要取得参数的个数。这样如果我们的 PHP 函数具有可变参数的话我们就可以只接收最小数量的参数。当然,如果你想操作剩下的参数,你可以用 zend_get_parameters_array_ex() 来得到。


这个参数解析函数还有一个带有附加标志的扩展版本,这个标志可以让你控制解析函数的某些动作。

intzend_parse_parameters_ex(intflags, intnum_args TSRMLS_DC, char *type_spec, ...);

这个标志(flags)目前仅接受 ZEND_PARSE_PARAMS_QUIET 这一个值,它表示这个函数不输出任何错误信息。这对那些可以传入完全不同类型参数的函数非常有用,但这样你也就不得不自己输出错误信息。


下面就是一个如何既可以接收 3 个长整形数又可以接收一个字符串的例子:

long l1, l2, l3;   
char *s;   
if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,ZEND_NUM_ARGS() TSRMLS_CC,"lll", &l1, &l2, &l3) == SUCCESS) {   
	/* manipulate longs */   
} 
else if(zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,ZEND_NUM_ARGS(), "s", &s, &s_len)==SUCCESS){
	/* manipulate string */   
} 
else{   
	php_error(E_WARNING, "%s() takes either three long values or a string as argument",   
	    get_active_function_name(TSRMLS_C));  
	return;   
}

我想你通过上面的那些例子就可以基本掌握如何接收和处理参数了。如果你想看更多的例子,请翻阅 PHP 源码包中那些自带的扩展的源代码,那里面包含了你可能遇到的各种情况。


以前的老式的获取参数的的方法(不推荐)

获取函数参数这件事情我们还可以通过 zend_get_parameters_ex() 来完成(不推荐使用这些旧式的 API,我们推荐您使用前面所述的新式的参数解析函数):

zval **parameter;
if(zend_get_parameters_ex(1, &parameter) != SUCCESS)
{
    WRONG_PARAM_COUNT;
}

所有的参数都存储在一个二次指向的 zval 容器里面(其实就是一个 zval* 数组,译者注)。上面的这段代码尝试接收 1 个参数并且将其保存在 parameter 所指向的位置。


zend_get_parameters_ex() 至少需要两个参数。第一个参数表示我们想要接收参数的个数(这个值通常是对应于 PHP 函数参数的个数,由此也可以看出事先对调用语法正确性的检查是多么重要)。第二个参数(包括剩下的所有参数)指向一个二次指向 zval 的指针。(即 ***zval,是不是有点糊涂了?^_^)这些指针是必须的,因为 Zend 内部是使用 **zval 进行工作的。为了能被在我们函数内部定义的**zval局部变量所访问,我们就必须在用一个指针来指向它。


zend_get_parameters_ex() 的返回值可以是 SUCCESS 或> FAILURE,分别表示参数处理的成功或失败。如果处理失败,那最大的可能就是由于没有指定一个正确的参数个数。如果处理失败,则应该使用宏 WRONG_PARAM_COUNT 来退出函数。


如果想接收更多的的参数,可以用类似下面一段的代码来处理:

zval **param1, **param2, **param3, **param4;
if(zend_get_parameters_ex(4, &param1, &param2, &param3, &param4) != SUCCESS)
{
    WRONG_PARAM_COUNT;
}

zend_get_parameters_ex() 仅检查你是否在试图访问过多的参数。如果函数有 5 个参数,而你仅仅接收了其中的 3 个,那么你将不会收到任何错误信息,zend_get_parameters_ex() 仅返回前三个参数的值。再次调用 zend_get_parameters_ex() 也不会获得剩下两个参数的值,而还是返回前三个参数的值。


接收可变(可选)参数

如果你想接收一些可变参数,那用前面我们刚刚讨论的方法就不太合适了,主要是因为我们将不得不为每个可能的参数个数来逐行调用 zend_get_parameters_ex(),显然这很不爽。


为了解决这个问题,我们可以借用一下 zend_get_parameters_array_ex() 这个函数。它可以帮助我们接收不定量的参数并将其保存在我们指定的地方:

zval **parameter_array[4];   
/* 取得参数个数 */   
argument_count = ZEND_NUM_ARGS();   
/ * 看一下参数个数是否满足我们的要求:少2个,多4个 。* /   
if(argument_count < 2 || argument_count > 4)   
	WRONG_PARAM_COUNT;   
/* 参数个数正确,开始接收。 */   
if(zend_get_parameters_array_ex(argument_count, parameter_array ) != SUCCESS)   
	WRONG_PARAM_COUNT;

让我们来看看这几行代码。首先代码检查了传入参数的个数,确保在我们可接受的范围内;然后就调用 zend_get_parameters_array_ex() 把所有有效参数值的指针填入 parameter_array。


我们可以在 fsockopen() 函数(位于ext/standard/fsock.c )中找到一个更为漂亮的实现。代码大致如下,你也不用担心还没有弄懂全部的函数,因为我们很快就会谈到它们。


例3.6 PHP中带有可变参数的 fsockopen() 函数的实现

pval **args[5];   
int *sock=emalloc(sizeof(int));   
int *sockp;   
int arg_count=ARG_COUNT(ht);   
int socketd = -1;   
unsigned char udp = 0;   
struct timeval timeout = { 60, 0 };   
unsigned short portno;   
unsigned long conv;   
char *key = NULL;   
FLS_FETCH();   
if(arg_count>5||arg_count<2||zend_get_parameters_array_ex(arg_c ount,args)==FAILURE) {   
	CLOSE_SOCK(1);   
	WRONG_PARAM_COUNT;   
}   
switch(arg_count) {   
	case 5:   
		convert_to_double_ex(args[4]);   
		conv = (unsigned long) (Z_DVAL_PP(args[4]) * 1000000.0);   
		timeout.tv_sec = conv / 1000000;   
		timeout.tv_usec = conv % 1000000;   /* fall-through */   
	case 4:   
		if (!PZVAL_IS_REF(*args[3])) {   
			php_error(E_WARNING,”error string argument to fsockopen not pas sed by reference”);   
		}   
		pval_copy_constructor(*args[3]);   
		ZVAL_EMPTY_STRING(*args[3]);   
		/* fall-through */   
	case 3:   
		if (!PZVAL_IS_REF(*args[2])) {   
		php_error(E_WARNING,”error argument to fsockopen not passed by reference”);   
			return;   
		}   
		ZVAL_LONG(*args[2], 0);   
		break;  
}   
convert_to_string_ex(args[0]);   
convert_to_long_ex(args[1]);   
portno = (unsigned short) Z_LVAL_P(args[1]);  
key = emalloc(Z_STRLEN_P(args[0]) + 10);

fsockopen() 可以接收 2-5 个参数。在必需的变量声明之后便开始检查参数的数量范围。然后在一个 switch 语句中使用了贯穿(fall-through)法来处理这些的参数。这个 switch 语句首先处理最大的参数个数(即 5),随后依次处理了参数个数为 4 和 3 的情况,最后用 break 关键字跳出 switch 来忽略对其他情况下参数(也就是只含有 2 个参数情况)的处理。这样在经过 switch 处理之后,就开始处理参数个数为最小时(即 2)的情况。


这种像楼梯一样的多级处理方法可以帮助我们很方便地处理一些可变参数。


存取参数

为了存取一些参数,让每个参数都具有一个明确的(C)类型是很有必要的。但 PHP 是一种动态语言,PHP 从不做任何类型检查方面的工作,因此不管你想不想,调用者都可能会把任何类型的数据传到你的函数里。比如说,如果你想接收一个整数,但调用者却可能会给你传递个数组,反之亦然 - PHP 可不管这些的。


为了避免这些问题,你就必须用一大套 API 函数来对传入的每一个参数都做一下强制性的类型转换。(见表3.4 参数类型转换函数)


注意:所有的参数转换函数都以一个 **zval 来作为参数。


表3.4 参数类型转换函数

函数说明
convert_to_boolean_ex()强制转换为布尔类型。若原来是布尔值则保留,不做改动。长整型值0、双精度型值0.0、空字符串或字符串‘0’还有空值 NULL 都将被转换为 FALSE(本质上是一个整数 0)。数组和对象若为空则转换为 FALSE,否则转为 TRUE。除此之外的所有值均转换为 TRUE(本质上是一个整数 1)。
convert_to_long_ex()强制转换为长整型,这也是默认的整数类型。如果原来是空值NULL、布尔型、资源当然还有长整型,则其值保持不变(因为本质上都是整数 0)。双精度型则被简单取整。包含有一个整数的字符串将会被转换为对应的整数,否则转换为 0。空的数组和对象将被转换为 0,否则将被转换为 1。
convert_to_double_ex()强制转换为一个双精度型,这是默认的浮点数类型。如果原来是空值 NULL 、布尔值、资源和双精度型则其值保持不变(只变一下变量类型)。包含有一个数字的字符串将被转换成相应的数字,否则被转换为 0.0。空的数组和对象将被转换为 0.0,否则将被转换为 1.0。
convert_to_string_ex()强制转换为数组。若原来就是一数组则不作改动。对象将被转换为一个以其属性为键名,以其属性值为键值的数组。(方法强制转换为字符串。空值 NULL 将被转换为空字符串。布尔值 TRUE 将被转换为 ‘1’,FALSE 则被转为一个空字符串。长整型和双精度型会被分别转换为对应的字符串,数组将会被转换为字符串‘Array’,而对象则被转换为字符串‘Object’。
convert_to_array_ex(value)强制转换为数组。若原来就是一数组则不作改动。对象将被转换为一个以其属性为键名,以其属性值为键值的数组。(方法将会被转化为一个‘scalar’键,键值为方法名)空值 NULL 将被转换为一个空数组。除此之外的所有值都将被转换为仅有一个元素(下标为 0)的数组,并且该元素即为该值。
convert_to_object_ex(value)强制转换为对象。若原来就是对象则不作改动。空值 NULL 将被转换为一个空对象。数组将被转换为一个以其键名为属性,键值为其属性值的对象。其他类型则被转换为一个具有‘scalar’属性的对象,‘scalar’属性的值即为该值本身。
convert_to_null_ex(value)强制转换为空值 NULL。

在你的参数上使用这些函数可以确保传递给你的数据都是类型安全的。如果提供的类型不是需要的类型,PHP 就会强制性地返回一个相应的伪值(比如空字符串、空的数组或对象、数值 0 或布尔值的 FALSE 等)来确保结果是一个已定义的状态。


下面的代码是从前面讨论过的模块中摘录的,其中就用到了这些转换函数:

zval **parameter;   
if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &parame ter) != SUCCESS))   {   
	WRONG_PARAM_COUNT;   
}   
convert_to_long_ex(parameter);   
RETURN_LONG(Z_LVAL_P(parameter));

在收到参数指针以后,参数值就被转换成了一个长整型(或整形),转换的结果就是这个函数的返回值。如果想要弄懂如何存取到这个返回值,我们就需要对 zval 有一点点认识。它的定义如下:


例3.7 PHP/Zend zval 类型的定义

typedef pval zval;   
typedef struct _zval_struct zval;   
typedef union _zvalue_value {   
	long lval; /* long value */   
	double dval; /* double value */  
	struct {   
		char *val;   
		int len;   
	} str;   
	HashTable *ht; /* hash table value */   
	struct {   
		zend_class_entry *ce;   
		HashTable *properties;   
	} obj;   
} zvalue_value; 
  
struct _zval_struct {   
	/* Variable information */   
	zvalue_value value; /* value */   
	unsigned char type; /* active type */   
	unsigned char is_ref;   
	short refcount;   
};

实际上,pzval(定义在 php.h)就是 zval(定义在 zend.h)的一个别名,都是 _zval_struct 结构的一个别名。_zval_struct 是一个很有趣的结构,它保存了这个结构的真实值 value、类型 type 和引用信息 is_ref。字段 value 是一个 zvalue_value 联合,根据变量类型的不同,你就可以访问不同的联合成员。对于这个结构的描述,可参见“表3.5 Zend zval 结构”、“表3.6 Zend zvalue_value 结构”和“表3.7 Zend 变量类型”。


表3.5 Zend zval 结构

字段说明
value变量内容的联合,参见“表3.6 Zend zvalue_value 结构”。
type变量的类型。“表3.7 Zend 变量类型”给出了一个完整的变量类型列表。
is_ref0 表示这个变量还不是一个引用。1 表示这个变量还有被别的变量所引用。
refcount表示这个变量是否仍然有效。每增加一个对这个变量的引用,这个数值就增加 1。反之,每失去一个对这个变量的引用,该值就会减1。当引用计数减为0的时候,就说明已经不存在对这个变量的引用了,于是这个变量就会自动释放。

表3.6 Zend zvalue_value 结构

字段说明
lval如果变量类型为 IS_LONG、IS_BOOLEAN 或 IS_RESOURCE 就用这个属性值。
dval如果变量类型为 IS_DOUBLE 就用这个属性值。
str如果变量类型为 IS_STRING 就访问这个属性值。它的字段 len 表示这个字符串的长度,字段 val 则指向该字符串。由于 Zend 使用的是 C 风格的字符串,因此字符串的长度就必须把字符串末尾的结束符 0×00 也计算在内。
ht如果变量类型为数组,那这个 ht 就指向数组的哈希表入口。
obj如果变量类型为 IS_OBJECT 就用这个属性值。

表3.7 Zend 变量类型

类型常量说明
IS_NULL表示是一个空值 NULL。
IS_LONG是一个(长)整数。
IS_DOUBLE是一个双精度的浮点数。
IS_STRING是一个字符串。
IS_ARRAY是一个数组。
IS_OBJECT是一个对象。
IS_BOOL是一个布尔值。
IS_RESOURCE是一个资源(关于资源的讨论,我们以后会在适当的时候讨论到它)。
IS_STRING是一个常量。

想访问一个长整型数,那你就访问 zval.value.lval;想访问一个双精度数,那你就访问 zval.value.dval,依此类推。不过注意,因为所有的值都是保存在一个联合里面,所以如果你用了不恰当的字段去访问,那就可能会得到一个毫无意义的结果。


访问一个数组和对象可能会稍微复杂些,稍后再说。


处理通过引用传递过来的参数

如果函数里面的参数是通过引用传递进来的,但是你又想去修改它,那就需要多加小心了。


根据我们前面所讨论的知识,我们还没有办法去修改一个经 PHP 函数参数传进来的 zval 。当然你可以修改那些在函数内部创建的局部变量的 zval ,但这并代表你可以修改任何一个指向 Zend 自身内部数据的 zval (也就是那些非局部的 zval)!


这是为什么呢?我想你可能注意到了,我们前面讨论的 API 函数都是类似于 *_ex() 这样子的。比如我们用 zend_get_parameters_ex() 而不用 zend_get_parameters(),用 convert_to_long_ex() 而不用 convert_to_long() 等等。这些 *_ex() 函数被称为新的“扩展”的 Zend API,它们的速度要快于对应的传统 API,但副作用是它们只提供了只读访问机制。


因为 Zend 内部是靠引用机制来运行的,因此不同的变量就有可能引自同一个 value (zval 结构的字段 value)。而修改一个 zval 就要求这个 zval 的 value 必须是独立的,也就是说这个 value 不能被其他 zval 引用。如果有一个 zval 里面的 value 还被其他 zval 引用了,你也同时把这个 value 给修改了,那你也同时就把其他 zval 的 value 给修改了,因为它们的 value 只是简单地指向了这个 value 而已。


但 zend_get_parameters_ex() 是根本不管这些的,它只是简单地返回一个你所期望的那个 zval 的指针。至于这个 zval 是否还存在其他引用,who care?(所以我们说这些 *_ex() 只提供了只读机制,并没有提供可写机制。你若利用 *_ex() 的结果强行赋值也是可以的,但这样就没法保证数据安全了。译注)。而和这个 API 对应的传统 API zend_get_parameters () 就会即时检查 value 的引用情况。如果它发现了对 value 的引用,它就会马上再重新创建一个独立的 zval ,然后把引用的数据复制一份到新的刚刚申请的空间里面,然后返回这个新的 zval 的指针。


这个动作我们称之为“zval 分离(或者 pval 分离)”。由于 *_ex()函数并不执行“zval 分离”操作,因此它们虽然快,但是却不能用于进行写操作。


但不管怎样,要想修改参数,写操作是不可避免的。于是 Zend 使用了这样一个特别的方式来处理写操作:无论何时,只要函数的某个参数使用过引用传递的,那它就自动进行 zval 分离。这也就意味着不管什么时间,只要你像下面这样来调用一个 PHP 函数,Zend 就会自动确保传入的是一个独立的 value 并处于“写安全”状态:

my_function(&$parameter);

但这不是一般参数(指不带 & 前缀但也是引用的参数,译者注)的情况。所有不是直接通过引用(指不带 & 前缀)传递的参数都将只是处在一种“只读”状态(其实这里的“只读”状态可以理解为“写不安全”状态)。


这就要求你确认是否真的在同一个引用打交道,否则你可能会收到你不太想要的结果。我们可以使用宏 PZVAL_IS_REF 来检查一个参数是否是通过引用传递的。这个宏接收一个 zval* 参数。“例3.8 检查参数是否经引用传递”给出了这样一个例子:


例3.8 检查参数是否经引用传递

zval *parameter;   
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &para meter) == FAILURE)   
	return;   
/* 检查参数是否经引用传递 */   
if (!PZVAL_IS_REF(parameter)) {  
	 zend_error(E_WARNING, "Parameter wasn't passed by reference");   
	 RETURN_NULL();   
}   
/* 改变这个参数 */   
ZVAL_LONG(parameter, 10);


确保其他情况下某些参数的写安全

有时候你可能会遇到过这种情况:你想对用 zend_get_parameters_ex() 接收的但是没有通过引用传递的一个参数进行写操作。这时你可以用宏 SEPARATE_ZVAL 来手工进行 zval 分离操作。这样可以得到一个新创建的与原来内部数据独立的 zval,但这个 zval 仅在局部有效,它可以被修改或销毁而不影响外部的全局 zval 。

zval **parameter;

/* 接收参数 */
zend_get_parameters_ex(1, &parameter);

/* 此时仍然关联在 Zend 的内部数据缓冲区 *//* 现在将“写安全”化 */
SEPARATE_ZVAL(parameter);

/* 现在你可以放心大胆去修改了,无需担心外部的 zval 会受到影响 */// ……

因为宏 SEPARATE_ZVAL 通过 emalloc() 函数来申请一个新的 zval,所以这也就意味着如果你不主动去释放这段内存的话,那它就会直到脚本中止时才被释放。如果你大量调用这个宏却没有释放,那它可能会瞬间塞满你的内存。


注意:因为现在已经很少遇到和需要传统 API(诸如 zend_get_parameters() 等等)了(貌似它有点过时了),所以有关这些 API 本节不再赘述。