Zend API 二(重要) (自用备注)

Zend API:深入 PHP 内核 (九)关于模块代码的讨论

模块结构

所有的 PHP 模块通常都包含以下几个部分:(对照my_module.c文件)

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

      2. 声明导出函数(用于 Zend 函数块的声明); (ZEND_FUNCTION ( my_function ))

      3. 声明 Zend 函数块;(zend_function_entry)

      4. 声明 Zend 模块;(zend_module_entry)

      5. 实现 get_module() 函数; (ZEND_GET_MODULE(my_module) )

      6. 实现导出函数。(PHP_FUNCTION)

 

1 包含头文件:

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

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

 

 

2 声明导出函数(ZEND_FUNCTION (my_function ))

      为了声明导出函数(也就是让其成为可以被 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

);

 

这个声明中的参数列表非常重要,你应该牢记于心。

 

 

表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() 来引用这个值。

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

 

 

3 声明 Zend 函数块(zend_function_entry)

 

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

zend_function_entry my_module_functions[] = {

      PHP_FE(my_module,NULL)           /* For testing, removelater. */

      {NULL, NULL, NULL}      /* Must be the last line inmy_module_functions[] */

};

 

zend_function_entry的内部定义如“例 3.4 zend_function_entry 的内部声明”所示:

typedefstruct _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。

 

 

你可能已经看到了,这个结构的最后一项是 {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可用来定义函数的宏”给出了一个可以用来定义一个函数的所有宏的列表:

宏

说明

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 的别名而已。(FUNCTION_ALIAS)

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_*系列的宏。

 

 

4  声明 Zend 模块(zend_module_entry)

 

      Zend 模块的信息被保存在一个名为zend_module_entry的结构,它包含了所有需要向Zend提供的模块信息。

 

zend_module_entrymy_module_module_entry = {

#ifZEND_MODULE_API_NO >= 20010901

       STANDARD_MODULE_HEADER,(size, zend_api, zend_debug and zts)

#endif

       "my_module",(模块名称)

       my_module_functions,(Zend 函数块的指针)

       PHP_MINIT(my_module),(模块启动函数)

       PHP_MSHUTDOWN(my_module),(模块关闭函数)

       PHP_RINIT(my_module), (请求启动函数)

       PHP_RSHUTDOWN(my_module), (请求关闭函数)

       PHP_MINFO(my_module),(模块信息函数)

#ifZEND_MODULE_API_NO >= 20010901

       "0.1", (模块版本号)

#endif

       STANDARD_MODULE_PROPERTIES(Remaining structure elements)

};

 

 

例3.5zend_module_entry 的内部声明

typedefstruct _zend_module_entry zend_module_entry;

struct_zend_module_entry {

      unsigned short size; (模块结构大小)

      int zend_api; (值为ZEND_MODULE_API_NO常量)

      unsigned char zend_debug; (是否为调试版本)

      unsigned char zts; (是否启用了ZTS Zend线程安全)

      char *name; (模块名称)

      zend_function_entry *functions; (Zend 函数块的指针)

      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”部分所显示的名称。

functions

Zend 函数块的指针, 这个我们在前面已经讨论过。

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_entryfirstmod_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 搭配使用。

 

 

5  实现 get_module() 函数

 

这个函数只用于动态可加载模块。

我们先来看一下如何通过宏 ZEND_GET_MODULE来创建这个函数:

#ifCOMPILE_DL_FIRSTMOD

ZEND_GET_MODULE(firstmod)

#endif

 

(C++:

#ifCOMPILE_DL_FIRSTMOD

BEGIN_EXTERN_C()

ZEND_GET_MODULE(firstmod)

END_EXTERN_C()

#endif)

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

 

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

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

 

6  实现导出函数

 

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

ZEND_FUNCTION(first_module)

{

      long parameter;

      if (zend_parse_parameters(ZEND_NUM_ARGS()TSRMLS_CC, "l", &parameter) == FAILURE) {

           return;

      }

      RETURN_LONG(parameter) ;

}

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

 

 

小结

      一切基本上就这样了 ―― 我们在实现一个模块时不会再遇到其他方面的事了。内建模块也基本上同动态模块差不多。

      因此,有了前面几节我们所掌握的信息,再在你遇到 PHP 源代码的时候你就有能力去搞定这些小麻烦。 在下面的几个小节里,我们将会学习到如何利用 PHP 内核来创建一个更为强大的扩展!

 

 

 

Zend API:深入 PHP 内核(十)  接收参数

 

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

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

 

 

取得参数数量

      没法根据函数的显式声明来对调用进行语法检查,而且它还支持可变参数,所以我们就不得不在所调

用函数的内部来获取参数个数。

      这个工作可以交给宏 ZEND_NUM_ARGS 来完成。(PHP4)在以前,这个宏(在 PHP3 中应该指的是宏 ARG_COUNT,因为 ZEND_NUM_ARGS 宏是直到PHP4.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 online 5”这样的错误信息。

 

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

ZEND_API void wrong_param_count(void);

#define WRONG_PARAM_COUNT { wrong_param_count(); return; }

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

 

取回参数

 

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

 

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

int zend_parse_parameters(int num_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 1parameter, 2 given

      Warning - wddx_deserialize() expectsparameter 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。

从PHP5.3开始, zend_parse_paramters_*函数新增了如下几个新的类型描述符:

f  - function or array containing php methodcall info (returned as

      zend_fcall_info andzend_fcall_info_cache)

H  - array or HASH_OF(object) (returned asHashTable*)

L  - long, limits out-of-range numbers toLONG_MAX/LONG_MIN (long)

Z  - the actual zval (zval**)

*  - variable arguments list (0 or more)

+  - variable arguments list (1 or more)

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

 

/* 取得一个长整数(l),一个字符串(s)和它的长度(s),再取得一个 zval(z)值。 */

longl;

char*s;

ints_len;

zval*param;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz", &l,&s, &s_len, &param) == FAILURE) {

      return;

}

 

/* 取得一个'由 my_ce 所指定的类'的(O)一个对象,另外再取得一个'可选的'(|)双精度的浮点数。 */

zval*obj;

doubled = 0.5;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d", &obj,my_ce, &d) == FAILURE) {

      return;

}

 

/* 取得一个对象(o)或空值,再取得一个数组。如果传递进来一个空对象,则 obj 将被设置为NULL。*/

zval *obj;

zval*arr;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &obj,&arr) == FAILURE) {

      return;

}

 

/* 取得一个分离(/)过的数组。*/

zval*arr;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &arr) ==FAILURE) {

return;

}

 

/* 仅取得前 3个参数(这对可变参数的函数很有用)  。*/

zval*z;

zend_boolb;

zval*r;

if(zend_parse_parameters(3, "zbr!", &z, &b, &r) == FAILURE){

      return;

}

 

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

 

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

int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char*type_spec, ...);

这个标志(flags)目前仅接受 ZEND_PARSE_PARAMS_QUIET这一个值,它表示这个函数不输出任何错误信息。

这对那些可以传入完全不同类型参数的函数非常有用,但这样你也就不得不自己输出错误信息。

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

longl1, 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 */

} elseif (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,

      ZEND_NUM_ARGS(), "s", &s,&s_len) == SUCCESS) {

      /* manipulate string */

} else{

      php_error(E_WARNING, "%s() takeseither 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;

intarg_count=ARG_COUNT(ht);

intsocketd = -1;

unsignedchar udp = 0;

structtimeval timeout = { 60, 0 };

unsignedshort portno;

unsignedlong conv;

char*key = NULL;

FLS_FETCH();

if(arg_count>5||arg_count<2||zend_get_parameters_array_ex(arg_count,args)==FAILUR

E) {

      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 tofsockopen not passed 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 tofsockopen 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,&parameter) != SUCCESS)){

      WRONG_PARAM_COUNT;

}

convert_to_long_ex(parameter);

RETURN_LONG(Z_LVAL_P(parameter));

 

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

typedefpval zval;

typedefstruct _zval_struct zval;

typedefunion _zvalue_value {

       (共用体,只能同时存储其中一种类型值,可节省空间, 当给另一种类型赋值时，其他类型的值会丢失)

      long lval; (如果变量类型为IS_LONG、IS_BOOLEAN或IS_RESOURCE就用这个属性值)

      double dval; (如果变量类型为IS_DOUBLE就用这个属性值)

      struct {

           char *val;

           int len;

      } str; (如果变量类型为IS_STRING就访问这个属性值)

      HashTable *ht; /* hash table value */ (如果变量类型为数组，那这个ht就指向数组的哈希表入口)

      struct {

           zend_class_entry *ce;

           HashTable *properties;

      } obj; (如果变量类型为IS_OBJECT就用这个属性值)

}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.6Zend zvalue_value 结构”和“表 3.7 Zend 变量类型”。

表3.5 Zendzval结构

字段

说明

value

变量内容的联合，参见“表3.6 Zend zvalue_value 结构”。

type

变量的类型。“表3.7 Zend 变量类型”给出了一个完整的变量类型列表。

is_ref

0 表示这个变量还不是一个引用。1 表示这个变量还有被别的变量所引用。(引用标识)

refcount

表示这个变量是否仍然有效。每增加一个对这个变量的引用，这个数值就增加 1。反之，每失去一个对这个变量的引用，该值就会减1。当引用计数减为0的时候，就说明已经不存在对这个变量的引用了，于是这个变量就会自动释放。(使用计数)

 

表3.6 Zendzvalue_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_CONSTANT

是一个常量。

      想访问一个长整型数，那你就访问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 检查参数是否经引用传递” 给出了这样一个例子:

zval*parameter;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z",&parameter) == FAILURE)

      return;

/*检查参数是否经引用传递 */

if(!PZVAL_IS_REF(parameter)) { {

      zend_error(E_WARNING, "Parameterwasn'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);

/*此时<parameter>仍然关联在Zend的内部数据缓冲区*/

/*现在将 <parameter> “写安全”化*/

SEPARATE_ZVAL(parameter);

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

......

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

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

 

 

 

Zend API:深入 PHP 内核(十一) 创建变量

 

当PHP脚本与扩展互相交换数据时,我们还需要做一件很重要的事情,那就是创建变量。这一小节将会展示如何处理那些 PHP 脚本所支持的变量类型。

 

要创建一个能够被 PHP 脚本所访问的“外部变量”

 

 

步骤：

      1 只需先创建一个zval容器；

      2 对这个zval结构进行必要的初始化填充；

      3 把它引入到Zend的内部符号表中就可以了；

 

zval*new_variable;

 

/*  1 申请并初始化一个新的的 zval 容器*/

MAKE_STD_ZVAL(new_variable);

/*  2 设置变量的类型和内容,见下  */

/*  3 将名为  "new_variable_name"  变量引入符号表  */

ZEND_SET_SYMBOL(EG(active_symbol_table),"new_variable_name", new_variable);

/*  现在就可以在脚本中用  $new_variable_name  来访问这个变量了  */

 

宏MAKE_STD_ZVAL 有以下两个动作：

      1  通过 ALLOC_ZVAL 来申请一个新的 zval 容器的内存空间

      2  调用 INIT_ZVAL将其初始化。(或INIT_PZVAL)

在当前的ZendEngine中,INIT_ZVAL  

      1  初始化zval容器的引用计数(refcount)置为 1

      2  还会把引用标识也清除(即把 is_ref 也置为 0)。

      在以后的 Zend Engine 中还可能会继续扩展这个 INIT_ZVAL 宏操作,因此我们推荐您使用MAKE_STD_ZVAL而非简单使用一个 ALLOC_ZVAL 来完成一个变量的创建工作。当然,如果您是想优化一下速度(或者是不想明确地初始化这个 zval 容器),那还是可以只用 ALLOC_ZVAL 来搞定的。不过我们并不推荐这么做,因为这将不能保证数据的完整性。

 

      ZEND_SET_SYMBOL

宏负责将我们新建的变量引入Zend内部的符号表。

这个宏会首先检查一下这个变量是否已经存在于符号表中,如果已经存在则将其转换为一个引用变量(同时会自动销毁原有的 zval 容器)。事实上这个方法经常用在某些速度要求并不苛刻但希望能少用一些内存的情况下。当然,要是你很在意程序的运行速度并且不在乎那一点点内存的话,那你可以跳过对相同名字变量存在性的检查而直接使用zend_hash_update() 函数强行将这个名字的变量插入符号表。(下面有实例)

 

      您可能注意到了 ZEND_SET_SYMBOL是通过宏 EG 来访问 Zend 执行器(executor)的全局结构的。特别的,如果你使用的是EG(active_symbol_table),那你就可以访问到当前的活动符号表,从而可以处理一些全局或局部变量。其中局部变量可能会依不同的函数而有所不同。

 

 

zend_hash_update()

实例：

zval*new_variable;

MAKE_STD_ZVAL(new_variable);

/*设置变量的类型和内容,见下*/

/*  将名为  "new_variable_name"  变量引入符号表  */

zend_hash_update(

   EG(active_symbol_table),

   "new_variable_name",

   strlen("new_variable_name")+ 1,

   &new_variable,

   sizeof(zval*),

   NULL

);

实际上这段代码也是很多扩展使用的标准方法。

      上面这段代码所产生的变量是局部变量,作用范围跟调用函数的上下文相关。如果你想创建一个全局变量那也很简单,方法还是老方法,只需换个符号表就可以了。

 

 

 

zval*new_variable;

MAKE_STD_ZVAL(new_variable);

/*  设置变量的类型和内容,见下  */

/*将名为 “new_variable_name” 变量引入全局符号表 */

ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name",new_variable);

 

      注意,现在宏 ZEND_SET_SYMBOL 使用的符号表是全局符号表EG(symbol_table)。另外,active_symbol_table是一个指针,而 symbol_table 却不是。这就是我们为什么分别使用EG(active_symbol_table) 和&EG(symbol_table)的原因-ZEND_SET_SYMBOL需要一个指针作为其参数。

 

当然,你同样也可以强行更新这个符号表：

zval*new_variable;

MAKE_STD_ZVAL(new_variable);

/*  设置变量的类型和内容,见下  */

/*将名为 “new_variable_name”变量引入全局符号表 */

zend_hash_update(

      &EG(symbol_table),

      “new_variable_name”,

      strlen(“new_variable_name”) + 1,

      &new_variable,

      sizeof(zval *),

      NULL

);

 

      例 3.9 “创建不同作用域的变量”向我们展示了创建一个局部变量(local_variable)和一个全局变量(global_variable)的过程。

 

      注意:  你可能会发现在PHP函数里似乎还不能直接访问这个全局变量(global_variable)

,因为你在使用前还必须使用 global$global_variable; 声明一下。

 

例3.9创建不同作用域的变量

ZEND_FUNCTION(variable_creation) {

      zval *new_var1, *new_var2;

      MAKE_STD_ZVAL(new_var1);

      MAKE_STD_ZVAL(new_var2);

      ZVAL_LONG(new_var1, 10);

      ZVAL_LONG(new_var2, 5);

      ZEND_SET_SYMBOL(EG(active_symbol_table), “local_variable”, new_var1);

      ZEND_SET_SYMBOL(&EG(symbol_table), “global_variable”, new_var2);

      RETURN_NULL();

}

 

 

长整型(整数)

 

      现在让我们以长整型变量起点,了解一下如何为一个变量赋值。PHP 中的整数全部是长整型,其值的存储方法也是非常简单的。看一下我们前面讨论过的 zval.value 容器的结构你就会明白,所有的长整型数据都是直接保存在这个联合中的lval 字段,相应的数据类型(type字段)为 IS_LONG(见 例 3.10 “长整型变量的创建”)。

 

例3.10长整型变量的创建:

 

zval*new_long;

MAKE_STD_ZVAL(new_long);

new_long->type= IS_LONG;

new_long->value.lval= 10;

 

或者你也可以直接使用ZVAL_LONG宏:

zval*new_long;

MAKE_STD_ZVAL(new_long);

ZVAL_LONG(new_long, 10);

返回长整型宏：RETURN_LONG(0)

 

 

双精度型(浮点数)

 

      PHP 中的浮点数都是双精度型,存储方法和整型差不多,也很简单。它的值是直接放在联合中的 dval字段,对应数据类型为 IS_DOUBLE。

zval*new_double;

MAKE_STD_ZVAL(new_double);

new_double->type= IS_DOUBLE;

new_double->value.dval= 3.45;

 

同样你也可以直接使用宏 ZVAL_DOUBLE:

zval*new_double;

MAKE_STD_ZVAL(new_double);

ZVAL_DOUBLE(new_double, 3.45);

返回长整型宏：RETURN_DOUBLE()

 

字符串

 

      字符串的存储可能会稍费点事。字符串的值是保存在 zval.value 容器中的str结构里面,相应的数据类型为IS_STRING。不过需要注意的是,前面我们已经提到过,所有与Zend内部数据结构相关的字符串都必须使用Zend自己的内存管理函数来申请空间。这样一来,就不能使用那些静态字符串(因为这种字符串的内存空间是编译器预先分配的)或通过标准函数(比如malloc()等函数)来申请空间的字符串。

 

 

zval*new_string;

char*string_contents = “This is a new string variable”;

MAKE_STD_ZVAL(new_string);

new_string->type= IS_STRING;

new_string->value.str.len= strlen(string_contents);

new_string->value.str.val= estrdup(string_contents);

 

请注意,在这我们使用了 estrdup() 函数。当然我们仍可直接使用一个预定义宏 ZVAL_STRING 来完成这项工作:

zval*new_string;

char*string_contents = “This is a new string variable”;

MAKE_STD_ZVAL(new_string);

ZVAL_STRING(new_string,string_contents, 1);

 

      ZVAL_STRING(zval,string_contents,duplicate)宏的第三个参数(duplicate副本)指明了该字符串是否需要被复制(使用estrdup()函数)。值为 1 将导致该字符串被复制,为0时则仅仅是简单地将其指向该变量的地址(即字符串地址,译注)。这项特性将会在你仅仅需要创建一个变量并将其指向一个已经由 Zend 内部数据内存时变得很有用。(简单的：1复制0指针)

 

 

如果你想在某一位置截取该字符串或已经知道了这个字符串的长度,那么可以使用宏ZVAL_STRINGL(zval,string,length, duplicate) 来完成这项工作。这个函数会额外需要一个表明该字符串长度地参数。这个宏不但速度上要比ZVAL_STRING 快,而且还是二进制安全的。

 

如果想创建一个空字符串,那么将其长度置 0 并且把empty_string 作为字符串的内容即可:

new_string->type= IS_STRING;

new_string->value.str.len= 0;

new_string->value.str.val= empty_string;

 

当然,我们也专门为您准备了一个相应的宏 ZVAL_EMPTY_STRING 来搞定这个步骤:

MAKE_STD_ZVAL(new_string);

ZVAL_EMPTY_STRING(new_string);

 

返回空字符串宏：RETURN_EMPTY_STRING()

返回空字符串宏：RETURN_STRINGL()

 

 

布尔类型

 

布尔类型变量的创建跟长整型差不多,只是数据类型为 IS_BOOL,并且字段lval所允许的值只能为 0 和1:

 

zval*new_bool;

MAKE_STD_ZVAL(new_bool);

new_bool->type= IS_BOOL;

new_bool->value.lval= 1;

也可以使用宏ZVAL_BOOL (需要另外指定一个值)来完成这件事情,或者干脆直接使用ZVAL_TRUE 或

ZVAL_FALSE 直接将其值设定为TRUE或FALSE。

返回宏：RETURN_BOOL() RETURN_TRUE() RETURN_FALSE()

 

 

数组

 

      数组在 Zend 内部是用哈希表(HashTable)来存储的,这个哈希表可以使用一系列的zend_hash_*() 函数来访问。因此我们在创建一个数组时必须先创建一个哈希表,然后再将其保存在 zval.value 容器的ht字段中。不过针对数组的创建我们现在另有一套非常方便API可供使用。为了创建一个数组,

我们可先调用一下 array_init()/*创建一个哈希表*/

函数:

zval*new_array;

MAKE_STD_ZVAL(new_array);

array_init(new_array);

array_init()函数总是返回SUCCESS。

 

      要给数组增加一个元素,根据实际需要,我们有 N 个函数可供调用。“表 3.8 用于关联数组的API” “表 3.9 用于索引数组的 API 第一部分”和“表3.10用于索引数组的 API 第二部分”有这些函数的说明。所有这些函数在调用成功时返回SUCCESS,在调用失败时返回FAILURE。

 

表3.8用于关联数组的API

函数

说明

add_assoc_long(zval *array, char *key, long n);

添加一个长整型元素。

add_assoc_unset(zval *array, char *key);

添加一个 unset 元素。

add_assoc_bool(zval *array, char *key, int b);

添加一个布尔值。

add_assoc_resource(zval *array, char *key, int r);

添加一个资源。

add_assoc_double(zval *array, char *key, double d);

添加一个浮点值。

add_assoc_string

(zval *array, char *key, char *str, int duplicate);

添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。

add_assoc_stringl(zval *array,

char *key, char *str, uint length, int duplicate);

添加一个指定长度的字符串。其余跟add_assoc_string () 相同。

add_assoc_zval

(zval *array, char *key, zval *value);

添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

 

 

表3.9用于索引数组的API第一部分

函数

说明

add_index_long(zval *array, uint idx, long n);

添加一个长整型元素。

add_index_unset(zval *array, uint idx);

添加一个 unset 元素。

add_index_bool(zval *array, uint idx, int b);

添加一个布尔值。

add_index_resource(zval *array, uint idx, int r);

添加一个资源。

add_index_double(zval *array, uint idx, double d);

添加一个浮点值。

add_index_string

(zval *array, uint idx, char *str, int duplicate);

添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。

add_index_stringl(zval *array,

uint idx, char *str, uint length, int duplicate);

添加一个指定长度的字符串。其余跟add_index_string () 相同。

add_index_zval(zval *array, uint idx, zval *value);

添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

 

 

表3.10用于索引数组的API第二部分(索引自增)

函数

说明

add_next_index_long(zval *array, long n);

添加一个长整型元素。

add_next_index_unset(zval *array);

添加一个 unset 元素。

add_next_index_bool(zval *array, int b);

添加一个布尔值。

add_next_index_resource(zval *array, int r);

添加一个资源。

add_next_index_double(zval *array, double d);

添加一个浮点值。

add_next_index_string

(zval *array, char *str, int duplicate);

添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。

add_next_index_stringl(zval *array,

char *str, uint length, int duplicate);

添加一个指定长度的字符串。其余跟add_next_index_string () 相同。

add_next_index_zval(zval *array, zval *value);

添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

 

所有这些函数都是对Zend内部hash API 的一种友好抽象。因此，若你愿意，你大可直接使用那些hash API进行操作。

      比方说，假如你已经有了一个zval容器并想把它插入到一个数组，那么你就可以直接使用zend_hash_update()来把它添加到一个关联数组(例3.11给关联数组添加一个元素)或索引数组(例3.12给索引数组添加一个元素)。

 

例3.11 使用zend_hash_update()给关联数组添加一个元素

 

zval*new_array, *new_element;

char*key = “element_key”;

MAKE_STD_ZVAL(new_array);

MAKE_STD_ZVAL(new_element);

 

array_init(new_array);

ZVAL_LONG(new_element,10);

if(zend_hash_update(new_array->value.ht,key, strlen(key) + 1, (void *)&new_element,

sizeof(zval*), NULL) == FAILURE){

      // do error handling here

}

 

例3.12 给索引数组添加一个元素

 

zval*new_array, *new_element;

intkey = 2;

MAKE_STD_ZVAL(new_array);

MAKE_STD_ZVAL(new_element);

 

array_init(new_array);

ZVAL_LONG(new_element,10);

if(zend_hash_index_update(new_array->value.ht,key,(void*) &new_element,sizeof(zval *), NULL) ==      FAILURE){

      // do error handling here

}

 

如果还想模拟下add_next_index_*() ,那可以这么做:

 

zend_hash_next_index_insert(ht,zval **new_element, sizeof(zval *), NULL)

 

      注意:  如果要从函数里面返回一个数组,那就必须首先对预定义变量return_value(return_value是我们导出函数中的一个预定义参数,用来存储返回值)使用一下array_init()函数。不过倒不必对其使用MAKE_STD_ZVAL。

 

      提示:为了避免一遍又一遍地书写new_array->value.ht,我们可以用HASH_OF(new_array)来代替。而且出于兼容性和风格上的考虑,我们也推荐您这么做。

 

 

对象

既然对象可以被转换成数组(反之亦然),那么你可能已经猜到了两者应该具有很多相似之处。实际上,对象就是使用类似的函数进行操作的,所不同的是创建它们时所用的 API。

 

我们可以调用 object_init() 函数来初始化一个对象:

zval*new_object;

MAKE_STD_ZVAL(new_object);

if(object_init(new_object) != SUCCESS){

      // do error handling here

}

可以使用“表3.11用于创建对象的 API”来给对象添加一些成员。

 

表3.11用于创建对象的API

函数

说明

add_property_long(zval *object, char *key, long l);

添加一个长整型类型的属性值。

add_property_unset(zval *object, char *key);

添加一个 unset 类型的属性值。

add_property_bool(zval *object, char *key, int b);

添加一个布尔类型的属性值。

add_property_resource(zval *object, char *key, long r);

添加一个资源类型的属性值。

add_property_double(zval *object, char *key, double d);

添加一个浮点类型的属性值。

add_property_string(zval *object,

char *key, char *str, int duplicate);

添加一个字符串类型的属性值。

add_property_stringl(zval *object,

char *key, char *str, uint length, int duplicate);

添加一个指定长度的字符串类型的属性值,速度要比add_property_string() 函数快,而且是二进制安全的

add_property_zval

(zval *obect, char *key, zval *container);

添加一个zval结构的属性值.  这在添加另外一个数组、对象等数据时会很有用

 

资源

 

      资源是PHP中一种比较特殊的数据类型。“资源”这个词其实并不特指某些特殊类型的数据,事实上,它指的是一种可以维护任何类型数据信息方法的抽象。所有的资源均保存在一个 Zend 内部的资源列表当中。列表中的每份资源都有一个指向可以表明其种类的类型定义的指针。Zend在内部统一管理所有对资源的引用。直接访问一个资源是不大可能的,你只能通过提供的 API 来对其进行操作。某个资源一旦失去引用,那就会触发调用相应的析构函数。

 

      举例来说,数据库连接和文件描述符就是一种资源。MySQL 模块中就有其“标准”实现。当然其他模块(比如Oracle模块)也都用到了资源。

 

注意:

 

      实际上,一个资源可以指向函数中任何一种你所感兴趣的数据(比如指向一个结构等等)。并且用户也只能通过某个资源变量来将资源信息传递给相应的函数。

 

      要想创建一个资源你必须先注册一个这个资源的析构函数。这是因为 Zend 需要了解当你把某些数据存到一个资源里后,如果不再需要这份资源时该如何将其释放。这个析构函数会在释放资源(无论是手工释放还是自动释放)时被 Zend 依次调用。析构函数注册后,

Zend会返回一个此种资源类型句柄。这个句柄会在以后任何访问此种类型的资源的时候被用到,

而且这个句柄绝大部分时间都保存在扩展的全局变量里面。这里你不需要担心线程安全方面的问题,因为你只是需要在模块初始化注册一次就行了。

 

下面是这个用于注册资源析构函数的 Zend 函数定义:

ZEND_APIint zend_register_list_destructors_ex(

rsrc_dtor_func_t ld,

rsrc_dtor_func_t pld,

char *type_name,

int module_number

);

 

      你或许已经注意到了,在该函数中我们需要提供两种不同的资源析构函数:一种是普通资源的析构函数句柄,一种是持久化资源的析构函数句柄。持久化资源一般用于诸如数据库连接等这类情况。在注册资源时,这两个析构函数至少得提供一个,另外一个析构函数可简单地设为NULL。

 

zend_register_list_destructors_ex() 接受以下几个参数：

ld

普通资源的析构函数。

pld

持久化资源的析构函数。

type_name

为你的资源指定一个名称。在 PHP 内部为某个资源类型起个名字这是个好习惯（当然名字不能重复）。用户调用 var_dump($resource) 时就可取得该资源的名称。

module_number

这个参数在你模块的 PHP_MINIT_FUNCTION 函数中会自动定义，因此你大可将其忽略。

返回值是表示该资源类型的具有唯一性的整数标识符，即资源类型句柄。

 

 

资源(不论是不是持久化资源)的析构函数都必须具有以下的函数原型:

void resource_destruction_handler(zend_rsrc_list_entry *rsrcTSRMLS_DC);

参数rsrc 指向一个zend_rsrc_list_entry结构:

typedef struct _zend_rsrc_list_entry {

            void*ptr;

            inttype;

            intrefcount;

} zend_rsrc_list_entry;

成员void*ptr才真正指向你的资源。

 

现在我们就知道该怎么开始了。

1    我们先定义一个将要注册到Zend内部的资源类型my_resource,这个类型的结构很简单,只有两个整数成员:

typedefstruct {

      int resource_link;

      int resource_type;

}my_resource;

 

2    接着我们再定义一下这种资源的析构函数。这个析构函数大致上是以下这个样子:

 

 

voidmy_destruction_handler(zend_rsrc_list_entry *rsrcTSRMLS_DC){

      // 先将无类型指针转换为我们的资源类型指针

      my_resource *my_rsrc = (my_resource *) rsrc->ptr;

      // 现在我们就可以随意处理这些资源了:像关闭文件、释放内存等等。

      // 当然也不要忘了释放资源本身所占用的内存!

      do_whatever_needs_to_be_done_with_the_resource(my_rsrc);

}

 

注意:

      有一个很重要的事情必须要提一下:如果你的资源是一个比较复杂的结构,比如包含有你在运行时所申请内存的指针等,那你就必须在释放资源本身前先释放它们!

 

定义步骤：

      1. 我们的资源是什么样子;

      2. 我们资源的析构函数是什么样子。

      3.创建一个在整个扩展范围内有效的全局变量用于保存资源类型句柄,这样就可以在每个需要它的函数中都能访问到它;

      4  给我们的资源类型定义一个名称;

      5. 完成前面定义的资源析构函数;

      6. 最后注册这个析构函数,及其他到一些附加资源、初始化全局变量、常量等等。

 

//3 在你扩展的某个地方定义一个表示资源类型的变量

static int le_myresource;

 

//4 给我们的资源起个名字是个很不错的习惯

#define le_myresource_name "My type of resource"

 

//5 现在完成我们资源的析构函数

void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC){

   my_resource *my_rsrc =(my_resource *) rsrc->ptr;

   do_whatever_needs_to_be_done_with_the_resource(my_rsrc);

}

 

PHP_MINIT_FUNCTION(my_extension) {

    //6 注意 'module_number' 已经在 PHP_MINIT_FUNCTION() 函数中被定义过了

    le_myresource =zend_register_list_destructors_ex(

                                        my_destruction_handler,

NULL,

                                       le_myresource_name,

module_number

);

    // 然后你可以在这里注册一些附加资源、初始化全局变量、常量等等。

}

      注册完这种资源的析构函数后,要真正注册一个资源(实例),我们可以使用zend_register_resource()函数或使用ZEND_REGISTER_RESOURE()宏。这两个的定义可以在zend_list.h中找到。尽管两者的参数定义是一一对应的,但使用宏通常可以得到更好的前向兼容性:

 

int ZEND_REGISTER_RESOURCE(zval*rsrc_result, void *rsrc_pointer,int rsrc_type); 

rsrc_result

这是一个初始化过 zval * 容器。

rsrc_pointer

指向所保存的资源。

rsrc_type

这个参数就是你在注册函数析构函数时返回的资源类型句柄。对上面的代码来说就是le_myresource le_myresource。

      返回值就是表示这个资源（实例）的具有唯一性的整数。

 

      那么在我们注册这个资源(实例)时究竟发生了什么事呢?函数会从 Zend 内部某个列表取得一个空闲空间,然后将资源指针及类型保存到这个空间。最后这个空闲空间的索引被简单地保存在给定的 zval * 容器里面:

 

rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);

if (rsrc_result) {

      rsrc_result->value.lval= rsrc_id;

      rsrc_result->type= IS_RESOURCE;

}

return rsrc_id;

 

      返回值 rsrc_id就唯一性地标识了我们新注册得到的那个资源。你可以使用宏RETURN_RESOURE来将其返回给用户:

      RETURN_RESOURCE(rsrc_id)

注意:

      如果你想立刻把这个资源返回给用户,那你就应该把return_value作为那个 zval *容器。这也是我们推荐的一种编程实践。

 

      Zend 引擎从现在就会开始跟踪所有对这个资源的引用。一旦对这个资源的引用全都不存在了,那么你在前面为这个资源所注册的析构函数就会被调用。这样做的好处就是你不用担心会在你的模块里面引入内存泄漏-你只需要把你调用脚本中所有需要分配的内存都注册成资源即可。这样一来,一旦脚本认为不再需要它们的时候,Zend就会找到它们然后再通知你(这就是callback,译注)。

      现在用户已经通过在某处传入到你函数的参数拿到了他的资源。zval * 容器中的value.lval 包含了你资源的标识符,然后他就可以宏 ZEND_FETCH_RESOURCE 来获取资源了:

 

ZEND_FETCH_RESOURCE(

      rsrc,

      rsrc_type,

      rsrc_id,

      default_rsrc_id,

      resource_type_name,

      resource_type

)

 

rsrc

这个指针将指向你前面已经声明过的资源。

rsrc_type

这个参数用以表明你想要把前面参数的那个指针转换为何种类型。比如 myresource * 等等

rsrc_id

这个是用户传进你函数的那个 zval *container 的地址。 假如给出的是 zval *z_resource ，那么此处就应该是 &z_resource。

default_rsrc_id

这个参数表明假如没有取到资源时默认指定的资源标识符。通常为 -1。

resource_type_name

所请求的资源类型资源类型名称。当不能找到资源时，就用这个字符串去填充系统由于维护而抛出的错误信息。

resource_type

这个可以取回在注册资源析构函数时返回的资源类型。在本例就是le_myresource。

 

      如果想从列表强行删除一个资源,可以使用zend_list_delete()函数。当然也可以强行增加引用计数,如果你知道你正在创建一个指向已分配内存资源的引用(比如说你可能想重用一个默认的数据库连接)

。对于这种情况你可以使用函数zend_list_addref()。想要查找一个已分配内存的资源,请使用zend_list_find()函数。关于这些操作的完整 API 请参见 zend_list.h。

自动创建全局变量的宏

 

      作为我们早期所谈论的一些宏的补充,还有一些宏可以让我们很方便的创建全局变量。了解了它们,我们在引入一些全局标识时就会感觉很爽,不过这个习惯可能会不太好。在“表 3.12 创建全局变量的宏”中描述了完成这些任务所用到的正确的宏。它们不需要申请任何 zval 容器,你只需简单地提供一个变量名和其值即可。

 

表3.12创建全局变量的宏

宏

说明

SET_VAR_STRING(name, value)

新建一个字符串变量。

SET_VAR_STRINGL(name, value, length)

新建一个指定长度的字符串变量。这个宏要比SET_VAR_STRING 快而且还是二进制安全的。

SET_VAR_LONG(name, value)

新建一个长整型变量。

SET_VAR_DOUBLE(name, value)

新建一个双精度变量。

 

 

创建常量

      Zend 支持创建真正的常量。访问常量时不需要 $ 前缀,而且常量是全局有效的。比如 TRUE 和 FALSE 这两个常量。

 

      要想创建一个常量,你可以使用“表 3.13 创建常量的宏”中所列举的宏来完成这项工作。所有的宏在创建常量时都必须指定一个名称和值。

 

      你还可以为常量指定一个特别的标识:

           •CONST_CS -

常量的名称是大小写敏感;

           •CONST_PERSISTENT -

     常量是持久化。换句话说,当携带这个常量的进程关闭时这个常量在剩下的请求中还依然有效,并不会被“遗忘”。

 

可以使用二进制的“或(OR)”操作来使用其中的一个或两个标识:

 

// 注册一个长整型常量

      REGISTER_LONG_CONSTANT(

”NEW_MEANINGFUL_CONSTANT”,

324,

CONST_CS | CONST_PERSISTENT

);

 

我们提供有两种不同类型的宏,分别是

      REGISTER_*_CONSTANT 和REGISTER_MAIN_*_CONSTANT。

第一种

类型在创建常量时只会绑定到当前模块。一旦注册这个模块的常量从内存中卸载,那么这个常量也就会随即消逝。

第二种

类型创建的变量将会独立于该模块,始终保存在符号表中。

表3.13 创建常量的宏

宏

说明

REGISTER_LONG_CONSTANT(name, value, flags)

REGISTER_MAIN_LONG_CONSTANT(name, value, flags)

新建一个长整型常量。

REGISTER_DOUBLE_CONSTANT(name, value, flags)

REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags)

新建一个双精度型常量。

REGISTER_STRING_CONSTANT(name, value, flags)

REGISTER_MAIN_STRING_CONSTANT(name, value, flags)

新建一个字符串常量。给定的字符串的空间必须在Zend 内部内存。

REGISTER_STRINGL_CONSTANT(name, value, length, flags)

REGISTER_MAIN_STRINGL_CONSTANT(name, value, length, flags)

新建一个指定长度的字符串常量。同样，这个给定的字符串的空间也必须在Zend 内部内存

 

 

 

 

Zend API:深入  PHP  内核(十二)  使用拷贝构造函数复制变量内容

 

      迟早你会遇到把一个zval 容器的内容赋给另外一个 zval 容器的情况。不过可别想当然,这事说起来容易做起来可有点难度。因为zval 容器不但包含了类型信息,而且还有对Zend 内部数据的一些引用。比如,数组以及对象等依据其大小大都或多或少包含了一些哈希表结构。而我们在将一个 zval 赋给另外一个zval 时,通常都没有复制这些哈希表本身,复制的只是这些哈希表的引用而已。

 

      为了能够正确复制这些复杂类型的数据,我们可以使用“拷贝构造函数(copyconstructor)”来完成这项工作。拷贝构造函数在某些为了可以复制复杂类型数据而支持操作符重载的语言中有着代表性的应用。如果你在这种语言中定义了一个对象,那你就可能想为其重载(Overloading)一下“=”操作符,这个操作符通常用于将右值(操作符右边表达式的值)赋给左值(操作符左边表达式的值)。

 

      “重载”就意味着将给予这个操作符另外一种不同的含义,它通常会把这个操作符跟某个函数调用关联起来。当这个操作符作用在一个对象上时,与之关联的函数就将会被调用,同时该操作符的左值和右值也会作为该函数的参数一并传入。这样,这个函数就可以完成“=”操作符想要完成的事情(一般是某些额外数据的复制)。

 

      这些“额外数据的复制”对 PHP 的zval 容器来说也是很有必要的。对于数组来说,“额外数据的复制”就是指另外再重建和复制那些与该数组有关的哈希表(因为当初我们复制 zval 时复制的仅仅是这些哈希表的指针)。而对字符串来说,“额外数据的复制”就意味着我们必须重新为字符串值去申请空间。如此类推。

 

      Zend Engine 会调用一个名为zval_copy_ctor()(在以前的 PHP 版本中这个函数叫做pval_copy_constructor() )的函数来完成这项工作。

 

      下面这个示例为我们展示了这样一个函数:它接收一个复杂类型的参数,在对其进行一定的修改后把它作为结果返回给PHP:

 

zval*parameter;

if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, “z”, &parameter) == FAILURE)

      return;

}

//在这对参数做一定的修改

......

//返回修改后的容器

*return_value= *parameter;

zval_copy_ctor(return_value);

 

      函数的头一部分没什么可说的,只是一段很平常的接收参数的代码而已。不过在对这个参数进行了某些修改后就变得有趣起来了:先是把parameter 容器值赋给了(预先定义好的)return_value 容器,然后为了能够真正复制这个容器,我们便调用了拷贝构造函数。这个拷贝构造函数能够直接处理它的参数,处理成功则返回 SUCCESS,否则返回 FAILURE。

 

      在这个例子当中如果你忘了调用这个拷贝构造函数，那么 parameter 和return_value 就会分别指向同一个 Zend 内部数据，也就是说返回值return_value 非法指向了一个数据结构。当你修改了参数parameter 时这个函数的返回值就可能会受到影响。因此为了创建一个独立的拷贝，我们必须调用这个函数。

 

      在Zend API 中还有一个与拷贝构造函数相对应的拷贝析构函数：zval_dtor()，它做的工作正好与拷贝构造函数相反。

 

 

Zend API:深入  PHP  内核(十三)  返回函数值

 

      关于扩展内函数到 PHP 脚本的返回值我们前面谈得比较少,这一节我们就来详细说一下。任何函数的返回值都是通过一个名为return_value 的变量传递的。这个变量同时也是函数中的一个参数。这个参数总是包含有一个事先申请好空间的 zval 容器,

因此你可以直接访问其成员并对其进行修改而无需先对return_value 执行一下 MAKE_STD_ZVAL 宏指令。

      为了能够更方便从函数中返回结果,也为了省却直接访问zval 容器内部结构的麻烦,ZEND提供了一大套宏命令来完成相关的这些操作。这些宏命令会自动设置好类型和数值。“表 3.14 从函数直接返回值的宏”和“表 3.15 设置函数返回值的宏”列出了这些宏和对应的说明。

 

      注意:使用“表 3.14 从函数直接返回值的宏”会自动携带结果从当前函数返回。而使用“表 3.15 设置函数返回值的宏”则只是设置了一下函数返回值,并不会马上返回。

 

表3.14从函数直接返回值的宏(会自动携带结果从当前函数返回)

宏

说明

RETURN_RESOURCE(resource)

返回一个资源。

RETURN_BOOL(bool)

返回一个布尔值。

RETURN_NULL()

返回一个空值。

RETURN_LONG(long)

返回一个长整数。

RETURN_DOUBLE(double)

返回一个双精度浮点数。

RETURN_STRING(string, duplicate)

返回一个字符串。duplicate 表示这个字符是否使用 estrdup() 进行复制。

RETURN_STRINGL(string, length, duplicate)

返回一个定长的字符串。其余跟 RETURN_STRING 相同。这个宏速度更快而且是二进制安全的。

RETURN_EMPTY_STRING()

返回一个空字符串。

RETURN_FALSE

返回一个布尔值假。

RETURN_TRUE

返回一个布尔值真。

 

表3.15设置函数返回值的宏(则只是设置了一下函数返回值,并不会马上返回)

宏

说明

RETVAL_RESOURCE(resource)

设定返回值为指定的一个资源。

RETVAL_BOOL(bool)

设定返回值为指定的一个布尔值。

RETVAL_NULL

设定返回值为空值

RETVAL_LONG(long)

设定返回值为指定的一个长整数。

RETVAL_DOUBLE(double)

设定返回值为指定的一个双精度浮点数。

RETVAL_STRING(string, duplicate)

设定返回值为指定的一个字符串，duplicate 含义同RETURN_STRING。

RETVAL_STRINGL(string, length, duplicate)

设定返回值为指定的一个定长的字符串。其余跟RETVAL_STRING 相同。这个宏速度更快而且是二进制安全的。

RETVAL_EMPTY_STRING

设定返回值为空字符串。

RETVAL_FALSE

设定返回值为布尔值假。

RETVAL_TRUE

设定返回值为布尔值真。

     

      如果需要返回的是像数组和对象这样的复杂类型的数据,那就需要先调用array_init()和object_init(),也可以使用相应的hash函数直接操作return_value。由于这些类型主要是由一些杂七杂八的东西构成，所以对它们就没有了相应的宏。

 

 

Zend API:深入  PHP  内核(十四)  信息输出

      就像我们在脚本中使用 print() 函数一样,我们也经常需要从扩展向输出流输出一些信息。在这方面-比如输出警告信息、phpinfo() 中对应的信息等一般性任务-PHP也为我们提供了一系列函数。这一节我们就来详细地讨论一下它们。

 

zend_printf()

      zend_printf() 功能跟printf() 差不多, 唯一不同的就是它是向 Zend 的输出流提供信息。

zend_error()

      zend_error() 用于创建一个错误信息。

      这个函数接收两个参数：

           第一个是错误类型（见zend_error.h）

           第二个是错误的提示消息

zend_error(E_WARNING,"This function has been called with empty arguments");

 

      “表3.16Zend 预定义的错误信息类型” 列出了一些可能的值（在PHP 5.0 及以上版本中又增加了一些错误类型，可参见 zend_error.h，译注）。这些值也可以用在 php.ini 里面，这样你的错误信息将会依照 php.ini 里面的设置，根据不同的错误类型而被选择性地记录。

 

表3.16Zend预定义的错误信息类型

错误类型

说明

E_ERROR

抛出一个错误，然后立即中止脚本的执行。

E_WARNING

抛出一个一般性的警告。脚本会继续执行。

E_NOTICE

抛出一个通知，脚本会继续执行。注意： 默认情况下 php.ini 会关闭显示这种错误。

E_CORE_ERROR

抛出一个 PHP 内核错误。通常情况下这种错误类型不应该被用户自己编写的模块所引用。

E_COMPILE_ERROR

抛出一个编译器内部错误。通常情况下这种错误类型不应该被用户自己编写的模块所引用。

E_COMPILE_WARNING

抛出一个编译器内部警告。通常情况下这种错误类型不应该被用户自己编写的模块所引用。

 

向  phpinfo() 中输出信息

      在创建完一个模块之后,你可能就会想往 phpinfo() 里面添加一些关于你自己模块的一些信息了

 

(默认是只显示你的模块名) PHP 允许你用 ZEND_MINFO() 函数向phpinfo() 里面添加一段你自己模块的信息。这个函数应该被放在模块描述块(见前文)部分,这样在脚本调用 phpinfo() 时模块的这个函数就会被自动调用。

 

      如果你指定了 ZEND_MINFO 函数,phpinfo() 会自动打印一个小节,这个小节的头部就是你的模块名。其余的信息就需要你自己去指定一下格式并输出了。

 

      一般情况下,你需要先调用一下 php_info_print_table_start(),然后再调用php_info_print_table_header()和 php_info_print_table_row() 这两个标准函数来打印表格具体的行列信息。这两个函数都以表格的列数(整数)和相应列的内容(字符串)作为参数。最后使用php_info_print_table_end() 来结束打印表格。“例 3.13 源代码及其在phpinfo() 函数中的屏幕显示”向我们展示了某个样例和它的屏幕显示效果。

 

例3.13  源代码及其  在  phpinfo() 函数中的屏幕显示

 

php_info_print_table_start();

php_info_print_table_header(2,"First column", "Second column");

php_info_print_table_row(2,"Entry in first row", "Another entry");

php_info_print_table_row(2,"Just to fill", "another row here");

php_info_print_table_end();

 

执行时信息

 

      你还可以输出一些执行时信息,像当前被执行的文件名、当前正在执行的函数名等等。

      当前正在执行的函数名可以通过 get_active_function_name()函数来获取。这个函数没有参数(译注:原文即是如此,事实上是跟后面提到的zend_get_executed_filename()函数一样需要提交TSRMLS_C 宏参数,译注),返回值为函数名的指针。

      当前被执行的文件名可以由 zend_get_executed_filename() 函数来获得。这个函数需要传入TSRMLS_C 宏参数来访问执行器全局变量。这个执行器全局变量对每个被 Zend 直接调用的函数都是有效的(因为TSRMLS_C是我们前文讨论过的参数宏INTERNAL_FUNCTION_PARAMETERS的一部分)。如果你想在其他函数中也访问这个执行器全局变量,那就需要现在那个函数中调用一下宏TSRMLS_FETCH()。

     

      最后你还可以通过 end_get_executed_lineno()函数来取得当前正在执行的那一行代码所在源文件中的行数。这个函数同样需要访问执行器全局变量作为其参数。关于这些函数的应用,请参阅“例3.14 输出执行时信息”。

 

例  3.14  输出执行时信息

zend_printf("Thename of the current function is %s<br>",

get_active_function_name(TSRMLS_C));

zend_printf("Thefile currently executed is %s<br>",

zend_get_executed_filename(TSRMLS_C));

zend_printf("Thecurrent line being executed is %i<br>",

zend_get_executed_lineno(TSRMLS_C));