启动函数和关闭函数会在模块的（载入时）初始化和（卸载时）反初始化时被调用，而且只调用这一次。正如我们在本章前面（见 Zend 模块描述块的说明）所提到的，它们是模块和请求启动和关闭时所发生的事件。

模块启动/关闭函数会在模块加载和卸载时被调用。请求启动/关闭函数会在每次处理一个请求时（也就是在执行一个脚本文件时）被调用。

对于动态加载的扩展而言，模块和请求的启动函数与模块和请求的关闭函数都是同时发生的（严格来说模块启动函数是先于请求启动函数被调用的，译注）。

可以用某些宏来声明和实现这些函数，详情请参阅前面的关于“Zend 模块声明”的讨论。

就像我们在脚本中使用 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.16 Zend 预定义的错误信息类型” 列出了一些可能的值（在 PHP 5.0 及以上版本中又增加了一些错误类型，可参见 zend_error.h，译注）。这些值也可以用在 php.ini 里面，这样你的错误信息将会依照 php.ini 里面的设置，根据不同的错误类型而被选择性地记录。

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

图3.3 在浏览器中显示警告信息

向 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()。

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

例 3.14 输出执行时信息

zend_printf("The name of the current function is %s", get_active_function_name(TSRMLS_C));
zend_printf("The file currently executed is %s", zend_get_executed_filename(TSRMLS_C));
zend_printf("The current line being executed is %i", zend_get_executed_lineno(TSRMLS_C));

关于扩展内函数到 PHP 脚本的返回值我们前面谈得比较少，这一节我们就来详细说一下。任何函数的返回值都是通过一个名为 return_value 的变量传递的。这个变量同时也是函数中的一个参数。这个参数总是包含有一个事先申请好空间的 zval 容器，因此你可以直接访问其成员并对其进行修改而无需先对 return_value 执行一下 MAKE_STD_ZVAL 宏指令。

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

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

表3.14 从函数直接返回值的宏

表3.15 设置函数返回值的宏

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

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

为了能够正确复制这些复杂类型的数据，我们可以使用“拷贝构造函数（copy constructor）”来完成这项工作。拷贝构造函数在某些为了可以复制复杂类型数据而支持操作符重载的语言中有着代表性的应用。如果你在这种语言中定义了一个对象，那你就可能想为其重载（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()，它做的工作正好与拷贝构造函数相反。

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

概述

要创建一个能够被 PHP 脚本所访问的“外部变量”，我们只需先创建一个 zval 容器，然后对这个 zval 结构进行必要的填充，最后再把它引入到 Zend 的内部符号表中就可以了。而且几乎所有变量的创建基本上都是这几个步骤：

zval *new_variable;

/* 申请并初始化一个新的的 zval 容器 */
MAKE_STD_ZVAL(new_variable);

/* 设置变量的类型和内容，见下 */
/* 将名为 "new_variable_name" 变量引入符号表 */
ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); 

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

宏 MAKE_STD_ZVAL 通过 ALLOC_ZVAL 来申请一个新的 zval 容器的内存空间并调用 INIT_ZVAL（查看 PHP4/5 的源代码可知此处可能为原文笔误，实际上应为 INIT_PZVAL，下同。译注）将其初始化。在当前的 Zend Engine 中，INIT_ZVAL 所负责的初始化工作除了将 zval 容器的引用计数（refcount）置为 1 之外，还会把引用标识也清除（即把 is_ref  也置为 0）。而且在以后的 Zend Engine 中还可能会继续扩展这个 INIT_ZVAL 宏操作，因此我们推荐您使用 MAKE_STD_ZVAL 而非简单使用一个 ALLOC_ZVAL 来完成一个变量的创建工作。当然，如果您是想优化一下速度（或者是不想明确地初始化这个 zval 容器），那还是可以只用 ALLOC_ZVAL 来搞定的。不过我们并不推荐这么做，因为这将不能保证数据的完整性。

ZEND_SET_SYMBOL 宏负责将我们新建的变量引入 Zend 内部的符号表。这个宏会首先检查一下这个变量是否已经存在于符号表中，如果已经存在则将其转换为一个引用变量（同时会自动销毁原有的 zval 容器）。事实上这个方法经常用在某些速度要求并不苛刻但希望能少用一些内存的情况下。

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

当然，要是你很在意程序的运行速度并且不在乎那一点点内存的话，那你可以跳过对相同名字变量存在性的检查而直接使用 zend_hash_update() 函数强行将这个名字的变量插入符号表。

zval *new_variable;

/* 申请并初始化一个新的的 zval 容器 */
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;
/* 申请并初始化一个新的的 zval 容器 */
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;

/* 申请并初始化一个新的的 zval 容器 */
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);

双精度型（浮点数）

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);

字符串

字符串的存储可能会稍费点事。字符串的值是保存在 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 宏的第三个参数指明了该字符串是否需要被复制（使用 estrdup() 函数）。值为 1 将导致该字符串被复制，为 0 时则仅仅是简单地将其指向该变量的值容器（即字符串地址，译注）。这项特性将会在你仅仅需要创建一个变量并将其指向一个已经由 Zend 内部数据内存时变得很有用。

如果你想在某一位置截取该字符串或已经知道了这个字符串的长度，那么可以使用宏 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);

布尔类型

布尔类型变量的创建跟长整型差不多，只是数据类型为 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。

数组

数组在 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

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

表3.10 用于索引数组的 API 第二部分

所有这些函数都是对 Zend 内部 hash API 的一种友好抽象。因此，若你愿意，你大可直接使用那些 hash API 进行操作。比方说，假如你已经有了一个 zval 容器并想把它插入到一个数组，那么你就可以直接使用 zend_hash_update() 来把它添加到一个关联数组（例3.11 给关联数组添加一个元素）或索引数组（例3.12 给索引数组添加一个元素）。

例3.11 给关联数组添加一个元素

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;
int key = 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

资源

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

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

注意:

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

要想创建一个资源你必须先注册一个这个资源的析构函数。这是因为Zend 需要了解当你把某些数据存到一个资源里后，如果不再需要这份资源时该如何将其释放。这个析构函数会在释放资源（无论是手工释放还是自动释放）时被 Zend 依次调用。析构函数注册后，Zend 会返回一个此种资源类型句柄。这个句柄会在以后任何访问此种类型的资源的时候被用到，而且这个句柄绝大部分时间都保存在扩展的全局变量里面。这里你不需要担心线程安全方面的问题，因为你只是需要在模块初始化注册一次就行了。

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

ZEND_API int 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() 接受以下几个参数：

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

资源（不论是不是持久化资源）的析构函数都必须具有以下的函数原型：

void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC);

参数 rsrc 指向一个 zend_rsrc_list_entry 结构：

typedef struct _zend_rsrc_list_entry {
    void *ptr;
    int type;
    int refcount;
} zend_rsrc_list_entry;

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

现在我们就知道该怎么开始了。我们先定义一个将要注册到 Zend 内部的资源类型 my_resource，这个类型的结构很简单，只有两个整数成员：

typedef struct {
    int resource_link;
    int resource_type;
} my_resource;

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

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);
}

注意:

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

OK。现在我们定义了

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

那么，我们还需要做哪些工作呢？我们还需要：

1. 创建一个在整个扩展范围内有效的全局变量用于保存资源类型句柄，这样就可以在每个需要它的函数中都能访问到它；
2. 给我们的资源类型定义一个名称；
3. 完成前面定义的资源析构函数；
4. 最后注册这个析构函数。

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

    // 给我们的资源起个名字是个很不错的习惯
    #define le_myresource_name  "My type of resource" 

   [...]

    // 现在完成我们资源的析构函数
    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) {
        // 注意 '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);

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

那么在我们注册这个资源（实例）时究竟发生了什么事呢？函数会从 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)

这个宏没有返回值。这对开发人员可能会方便了点。不过还是要注意添加 TSRM 参数和确认一下是否取回了资源。如果在接收资源时出现了问题，那它就会抛出一个警告信息并且会立刻从当前函数返回，其返回值为 NULL。

如果想从列表强行删除一个资源，可以使用 zend_list_delete() 函数。当然也可以强行增加引用计数，如果你知道你正在创建一个指向已分配内存资源的引用（比如说你可能想重用一个默认的数据库连接）。对于这种情况你可以使用函数 zend_list_addref() 。想要查找一个已分配内存的资源，请使用 zend_list_find() 函数。关于这些操作的完整 API 请参见 zend_list.h。

自动创建全局变量的宏

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

表3.12 创建全局变量的宏

创建常量

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 创建常量的宏

临近年关，可能大家都忙了些，因此虽然我们已经提前做了准备，并且遵守每双月 1 号发布一期杂志的承诺，按时发布了新一期的杂志，但在编辑部内部还是感觉匆忙了些，希望下一期能有所改观。

这一期的杂志并没有我的文章，我也不再负责每期《PHP 新闻》和《编者按》，而纯粹是作为一个《安全与优化》栏目的编辑出现，现在看来自我感觉做得还不够好。坦白说，这个栏目还没有做到我心目中所要达到的高度，今后还要多多努力。

相对于第一期，这一期杂志厚度略显薄了一些。不过单就页码数（本期为 69 页）而言，我认为比较合适的。太少自然说不过去，太多则编辑压力太大，而且限于目前国内 PHP 的应用现状也会有巧妇难做无米之炊的感觉。

关于本期的文章，限于个人兴趣，我主要说说这方面的几篇文章。

先来说说我负责栏目的几篇文章。得益于近水楼台，我最先翻阅的是 heiyeluren（黑夜路人）的《分表处理设计思想和实现》这篇文章。看得出，heiyeluren 应该是一名实际经验非常丰富的 PHP 程序员了。不过我并不想再次赘述文章的内容，而是想说一个看他的几篇文章所得出来的一个非常有趣的看法：他在文末所提出问题的价值通常都高于文章本身的平均价值。:D 我甚至觉得那几个问题才是文章的点睛之笔。

除这篇文章外，还有两篇关于安全方面的文章，分别是残恤的《编写安全的 PHP 代码》和剑心的《变量没有初始化引起安全漏洞》。这两篇文章作为我个人来讲，是有点言犹未尽的感觉的。在和作者交流时，作者似乎也有类似的感觉。这可能是我催稿也有点晚，使两位作者未有充分的时间去酝酿，来不及把自己的想法完全舒展开来的缘故，下次一定要记得改进。

存储过程、触发器和视图是构建大中型应用中不可避免地所使用的技术手段，这方面特性的缺乏也是 MySQL 被经常诟病的地方之一。所幸 MySQL 已经意识到了这个问题，在 5.x 版本中已经加入了对这方面的支持。但令人遗憾的是介绍 MySQL 存储过程等新特性的文章并不多，尤其是中文文章。本期 welefen 的《MySQL 中的存储过程、触发器和视图》一篇文章相信会对很多朋友有所帮助。

h058 的《JavaScript 效率测试》一文我也仔细的看了一遍。由于我对 JavaScript 的内部结构不太熟悉，所以也是感觉收获颇丰。

另外还有李辉的《Smarty 结合 ajax 无刷新留言本实例解析》、周路明的《PHPChina 留言本实例》系列连载教程都是很不错的技术文章，是刚进 PHP 大门朋友的一份很好的参考资料。

其他都是些非技术性文章，就不多说了，感兴趣的可以去看看，放松一下。：）

经过 N 次的跳票和等待，PHP 5.2.0 已于 11 月 2 日正式发布。根据 PHP 小组不成文的开发习惯，PHP 5.0 系列更大程度上像一个技术展示版，性能低下（甚至还不如 PHP4，这主要归结与 Zend 中重写的更加强大也更加复杂的OO 机制），稳定性也有所欠缺，目前 PHP 开发组已经放弃了对这个系列的开发。PHP 5.1 系列则侧重于对性能的改善，和 PHP 5.0 系列已经不可同日而语。但随着 PHP5.2系列的发布，PHP 5.1 也已经和 PHP4.4 系列一样进入了维护状态，除非出现重大的 BUG 和安全隐患否则将不再更新。新发布的 PHP 5.2 除了修复了以往 200 多个 BUG 以外，它还将性能进一步提高，尤其是改善了在高负载情况下的表现，而且在安全性的处理上也做出了很大的改进。同时也增加了很多很实用的技术（比如 JSON、Zip等支持），另外还有一些原本定为 PHP6 的特性也已经被提前实现在这个版本当中。可以说，相对于最初的 PHP5 版本，这次的改变几乎是半革命性的（革命性这个形容词当然是留给 PHP6 的 ：D）。下面我自己掌握的一些信息和理解，尝试向大家介绍一下 PHP 5.2的新特性，如有不当之处，还望方家斧正：

1、最明显的当属 PHP 5.2 在移除了filepro 和 hwapi 两个扩展（这两个被移动到了 PECL）的同时另外增加了4个新的扩展：Date、JOSN、Filter和ZIP。

其实从 PHP 5.1 开始，在 PHP 核心增加了一个 Date 扩展，重写了对日期/时间（主要是时区方面）的支持。所不同的是，PHP 5.2 更进一步，日期和时区则分别成为了类 DateTime 和 DateTimeZone 的一个对象。大家可以在 PHP CLI 中运行php –rc DateTime 或 php –rc DateTimeZone 来看一下这两个类的详细信息。需要注意的是如果你的程序中已经存在有名为 DateTime 或 DateTimeZone 类的话，那想在 PHP 5.2 中运行就必须改名了。(著名的开源 CRM ：vtigercrm 已经有了前车之鉴)

JSON 扩展实现了则实现对 JavaScript Object Notation (JSON) 这种轻量级数据交换格式的支持。在 PHP 5.2 中这个扩展是默认被启用的。

相信很多开发人员都为 PHP与 JavaScript 之间的通信发愁过，尤其是现在这个流行 Ajax 的时代。而现在，我们用JSON 就可以很轻易的解决这个问题。JSON 数据能够直接为服务器端代码使用, 并且也能够让客户端的 JavaScript简单地通过 eval() 来进行读取，这就大大简化了服务器端和客户端的代码开发量。虽然以前在 PHP 里面也有一些 JSON 类来支持，但这哪有 PHP 的原生支持来得高效和快捷呢？Filter 扩展负责校验和过滤数据，这个扩展主要是为了处理像用户的输入那样的不可靠数据而设计的。这个扩展也是默认被启用的。默认情况下的RAW 模式将不会以任何方式影响输入的数据，也就是说这不会对现有代码产生任何影响。但我们在以后的开发中应该尽可能地利用这个扩展来进行敏感字符的过滤，因为这不但简化了一些表单的验证工作，而且提高了程序的安全性和运行效率。 ZIP 扩展将允许我们对 Zip 压缩包及其包内的文件进行读写操作。也就是说，我们对 Zip文件不仅能看，而且还能摸：它提供了对 Zip 文件的完全支持。这项特性的应用是非常广泛的，具体带来的种种好处我就不再多说了。

当然，关于这些扩展的具体细节还得查阅我们无所不能的 PHP 手册。:D

2、改进了内存管理器，使之在高负载情况下具有更佳的表现。

按照 “Zend 二老”之一也就是 “Zend” 中那个 “nd” 的说法，这个新的内存管理器是分层（hierarchical）的。这个管理器共有三层：存储层（storage）、堆（heap）层和 emalloc/efree 层。存储层通过 malloc()、mmap() 等函数向系统真正的申请内存，并通过 free() 函数释放所申请的内存。存储层相当于 Zend 自己的“内存仓库”，通常申请的内存块都比较大。堆层（注意这里的堆并不是指操作系统所管理的堆，而是 Zend 内存管理器的所管理的内存堆）就把它们从存储层要过来并分割成一些较小的块。而 emalloc/efree 层就是指通过 PHP API 的 emalloc()/efree() 函数所申请和释放的内存。emalloc() 并不直接同存储层打交道，同它们接头的是堆层。负责把比原来的管理器在同等条件下会分配更小的内存，但速度更快。它首先会从系统（堆）中申请一些较大的内存块，然后自己来管理这个堆。php.ini 中的memory_limit 值虽然还会被检用，但已不再是每次 emalloc() 调用时都检用，而仅仅是在向系统申请那些大的内存块时被检用。

熟悉一些服务器端编程的朋友可能会马上想到一个词：内存池！没错，这基本上就是一个内存池。至少我是这么认为的。:D

内存池技术其实这是服务端编程中很常见。使用内存池技术可以有效地避免频繁的内存申请/释放操作，在内存池技术中，内存释放时实际上并没有通知操作系统真实的释放和回收，而仅仅是对将要释放的内存做个了标记，表示该部分内存已经不再使用。等下一次申请内存时，就从这些“可用”的内存链表中取出一个内存块，从而避免了频繁的内存申请/释放操作，大大节省了系统资源。根据测试和统计，在 PHP 4.4 版本中，一个典型的较为简单的请求就有超过 20,000次的对系统堆的申请和释放操作，这花费的时间相当于整个脚本所花费时间的 20% 左右。由此可见，若能降低这种资源消耗则效果是极为可观的。

与此同时，采用内存池技术也带来一个更为重要的“副作用”：避免了大量的“内存碎片”。一般情况下，内存碎片是对系统没有多大影响的，但服务端应用明显不同于一般应用，服务端会面临很高数量级的访问请求，这些请求也伴随着更高数量级的内存申请/释放操作。内存碎片过多将导致内存利用率降低，降低内存分配速度，严重时还会触发内存分配失败，尽管此时理论上仍有可分配的物理内存。

最后，内存池技术还有一个不太引人注意的好处：它能降低内存泄漏的概率。因为实际申请的内存块虽然尺寸较大，但数量较少，而且一般情况下都是统一申请，实际释放时也可以统一释放。显然，这比代码中即时申请，而没有即时释放所造成内存泄漏的概率要小很多。

不过采用内存池技术的管理器也明显要比常规管理器（指的是内存即时申请，即时释放的管理机制）的内存开销要大，因为除了真正申请的内存外，管理器还得负责维护每个内存块的状态，因此 PHP 5.2 中把 php.ini中 memory_limit 指令值从默认的 8M 提升为 16M 。这看似增加了内存消耗，并且也需要极少量的CPU资源来管理，但由于内存碎片的减少实际上并没有增加多少消耗，再结合其他方面的表现，可以说是所得远大于所失，尤其是在高负载情况下。

3、PHP 5.2 也对 INI 指令的存取方面做了优化。

PHPer 都知道，在 PHP 脚本中我们可以用 ini_set() 函数动态改变某个 PHP 指令的值。但问题是在请求结束后你还得把这些改变的值给恢复过来以保证下个脚本能正确使用。在 PHP 5.2 之前，PHP 的做法可谓是不辞劳苦，逐个遍历 INI 指令并恢复的。如果你是整个脚本都是 ini_set() 也就罢了（当然这个情况也是极其罕见的。：）），万一我的脚本中很少使用甚至根本就没有使用这个函数那我不就是亏大了？因此 PHP 5.2 为了解决这个问题又额外增加了一个表专门保存更改过的指令，这样就不用来回挨个恢复了。

4、PHP 5.2 还对 require_once() 和 include_once() 两个函数进行了优化。

PHP 5.2 以前 require_once() 和 include_once() 的做法是无论某个文件是否已经被缓存或编译过，统统是先 fopen() 再说，打开成功后在查询一下是否已经缓存过。这么处理的原因就是 在 PHP 5.1 以前没有很完美的解决 realpath() 相对路径和符号连接方面的问题。因为若不能唯一地正确地确定某个路径的真实路径表示那么你就无法利用这个路径的唯一性去解决某个问题。而 fopen 则没有这个顾虑。realpath() 的这个问题在 PHP 5.1 中被彻底搞定了，但还没来得及应用到 require_once() 和 include_once() ，结果就拖迟到现在。解决这个问题的好处是在于避免了 fopen 这个 I/O 操作，在很多高负载情形中，通常都是 数据库、网络或者磁盘 I/O 而不是 CPU 成为瓶颈。

5、对HashTable 的复制也进行了优化。

HashTable在ZendEngine是一个很基本的数据结构，数组本质上就是一个 HashTable。对HashTable 的优化也将意味着对数组的复制操作（无论是显式还是隐式）速度将会有一定的提升。

6、其他的一些性能方面的改进。

PHP 5.2 也对在FastCGI SAPI 模块中访问环境变量的性能做了少许优化。以前则是逐行搜索，现在则是通过 Hash 值来存取。除此之外，PHP 5.2还对str_replace() 和 implode() 函数以及“try {} catch {}”块等都做了一定的优化。

还有一些对语言特性和安全特性方面的改进：

1、继PHP 5.0增加了一个 E_STRICT的错误报告级别（常量值为 2048）之后，PHP 5.2 也新增了一个错误报告

级别：E_RECOVERABLE_ERROR ，其常量值为 4096 。

这个级别的错误主要是从E_ERROR中但可以被用户自定义的错误处理程序（一般通过set_error_handler() 函数指定）所捕捉的情况转化而来。如果一个E_RECOVERABLE_ERROR 未被捕捉并处理，那么它的表现就和所有 PHP 版本中的E_ERROR一样会导致程序中止。在错误日志中，该类型的错误将被记录成“可捕捉的致命错误（Catchable fatal error）”。

导致 PHP 抛出 E_RECOVERABLE_ERROR 的情况通常是指那些很危险，但还不足以让 Zend Engine 崩溃的情况。比方说，有下面一段代码：

class foo {
function bar(foo $a) { }
}
$a = new foo ;
$a->bar(new stdClass) ;
很明显，类 foo 的 bar 函数要求一个 foo 类型的参数，但实际代码中却给了一个 stdClass 类型的参数。在PHP 5.2 以前，这会导致一个 E_ERROR（Fatal error: Argument 1 passed to foo::bar() must be an instance of foo……）。但在 PHP 5.2（包括以后的 PHP6）则会导致一个E_RECOVERABLE_ERROR（Catchable fatal error: Argument 1 passed to foo::bar() must be an instance of foo……）。这种错误是可以被捕捉的，如果你通过set_error_handler() 指定了一个错误处理函数（即使是你在这个函数中没有处理E_RECOVERABLE_ERROR），那么程序就会继续运行。但如果你没有指定一个错误处理函数，那么这个 E_RECOVERABLE_ERROR 错误就会和 E_ERROR 一样，会立即导致程序中止。

2、相应的，错误报告级别 E_ALL 也将会包含上述E_RECOVERABLE_ERROR。

这也就意味着常量 E_ALL 的值将会从原来的2047 变为 6143。注意，在 PHP 5.0 和 PHP 5.1 中虽然增加了E_STRICT，但在这两个版本中 E_ALL 并不包含 E_STRICT。而在以后的版本（如 PHP5.2、PHP6等）中 E_ALL 则包含了包括 E_STRICT 和 E_RECOVERABLE_ERROR 在内的所有错误级别。 在 PHP 5.0/5.1 中我们想设置error_reporting 为 E_ALL 就不得不采用error_reporting(E_ALL | E_STRICT) 的写法，感觉极为别扭，也很容易造成一些疏忽和误导。在 PHP5.2当中我们就没有这个苦恼了。另外如果你在 Apache 的配置文件（如 httpd.conf）或 .htaccess 文件中用error_reporting 设置了错误报告级别（比如：php_value error_reporting 4095），由于 Apache 不支持 PHP 常量 ，那你还得手工去适当调整这些错误报告级别的数值。

3、添加了allow_url_include 这个 ini 指令来辅助 allow_url_fopen 操作；

这个是 PHP 5.2 在安全方面的重大更新之一。使用这个指令可以让我们区分开对远程文件的标准文件操作和包含操作。我们通常需要进行前面的标准操作，而后面的包含操作则通常是危险的发源地。从 PHP 5.2 开始，你的本地脚本可以在禁止远程包含操作的同时进行标准远程文件操作。事实上，这个就是默认配置。 PHP 5.2 把原来的allow_url_fopen 指令分成了 allow_url_fopen 和 allow_url_include 两个指令。如果 allow_url_fopen 操作是禁止的，那么 allow_url_include 也将被禁止。默认情况下将会允许进行 allow_url_fopen 操作，但是禁止allow_url_include 。这样就能非常有效的避免远程代码注入（remote code injection）。这个本来也是打算在 PHP6中添加的，现在我们提前用到了。:D

4、PHP 5.2 增加了对接口中构造函数类型(签名) 强制性检查的支持。

从 PHP 5.2 开始，如果你在一个接口中声明了一个构造函数，那么在所有实现该接口的类都必须包含一个构造函数，并且这个构造函数要与该接口的构造函数的签名完全一致。这里术语“签名”的意思是函数的参数和返回值的类型（包括其语言类型以及是引用传递还是值传递），这个概念有点类似于C 语言中 “原型”。看以下代码：

interface constr {
function __construct() ;
}
class implem implements constr {
function __construct ($a) {
}
}

这段代码在 PHP 5.0和 PHP 5.1 里面运行是毫无问题的，但在 PHP 5.2 中则会抛出一个错误：Fatal error: Declaration of implem::__construct() must be compatible with that of constr::__construct()，提示类implem 的构造函数与接口constr 的构造函数的声明不匹配。

值得一提的是这项新特性的添加过程是很有意思，有兴趣的朋友可以到 Zend 的每周总结（http://www.zend.com/zend/week/week279.php#Heading9）里面看看来龙去脉，此处不再赘述。

5、__toString() 函数将会在任何合适的地方被调用。

魔术方法 __toString() 现在会在一个字符串上下文环境中被调用。换句话说，一个对象在任何地方都可以作为一个字符串来使用，只要它实现了 __toString() 函数。当然你实现的 __toString() 函数不能抛出异常，否则脚本将会中止运行。以前为防万一，PHP 5.0/5.1会在必要时会把对象标识(Id)作为一个字符串返回，这个特性在 PHP 5.2中已经被抛弃。因此这带来的问题就可能是不能保证一个对象的标识总是唯一的。如果你在程序中利用了对象标识符的唯一性，那这将会是某种缺陷。如果没有实现类的 __toString()函数但却把其对象作为作为一个字符串来使用就会导致一个“可捕捉的致命错误”。 还有个特例，就是对象也不能作为作为数组的索引或者键名，即使是它有一个 __toString() 方法。以后 PHP 可能会内建一个 Hash机制来提供对对象唯一性的支持，但就现在来说，你必须自己提供一个对象的 hash 算法，或者干脆就用新提供的 SPL 函数：spl_object_hash()；

6、为在写模式下访问 __get() 的返回值这种情况增加了E_NOTICE 级错误提示。

显然 __get() 函数只能在读模式下返回一个值，并且也不可能把一个值写入 __get() 函数。但在以前的版本中并没有为这种不正确的用法给予提示。从 PHP 5.2 开始将会为这种情况抛出一个E_NOTICE。注意：如果你对 foreach() 和其他的一些更改数组内部指针的函数也采取了同样的操作（即给 foreach 所“抽”出来的值进行赋值），那也会触发一个E_NOTICE ，因为这些“抽”出来的值都是处于读模式。如果你的代码中存在这种情况，那你应该把 __get() 函数的返回值转换为一个数组，或者用 SPL 里面的 ArrayObject 来代替这个数组。

7、丢弃了抽象静态的类函数。

由于“笔漏”，PHP 5.0 和 5.1 版本竟然允许类具有抽象静态函数，不过现在不行了。现在只允许接口有抽象静态函数。

8、其他一些语言特性的改变：

• － SPL 新增了正则迭代器(Regex Iterators)、文件对象（SplFileObject）的CSV 支持等。
• － 增加了对 RFC2397 （数据流）的支持。
• － 增加了对Apache 2.2的支持。
• － 现在可以在上传文件时实时取得文件的上传进度了。
• － 对PHP或其扩展所需 OpenSSL 库、PCRE 库、MySQL客户端库、PostgreSQL 客户端库、SQLite 库等均进行更新升级。

最后再来介绍一下 PHP 运行模式方面的改动：

1、首先是 PHP 5.2 改变了 Win32 环境下 PHPRC 环境变量的优先级。

在以前搜索 php.ini 的路径顺序为：
1. SAPI 模块所指定的位置（Apache 2 中的 PHPIniDir 指令，CGI 和 CLI 中的 -c 命令行选项，NSAPI 中的 php_ini 参数，THTTPD 中的 PHP_INI_PATH 环境变量）
2. HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath（Windows 注册表位置）
3. PHPRC 环境变量
4. 当前工作目录（对于 CLI）
5. web 服务器目录（对于 SAPI 模块）或 PHP 所在目录（Windows 下其它情况）
6. Windows 目录（C:\windows 或 C:\winnt），或 –with-config-file-path 编译时选项指定的位置现在 PHPRC 环境变量由第三优先权变为第二优先权，高于Windows 注册表所指定的位置。

2、PHP 的命令行模式（CLI SAPI）不再在CWD（当前工作目录）里查找 php.ini 或php-cli.ini 文件。

在 PHP 5.1.x 中有一个未公开的特性就是 CLI 会自动在当前目录中搜索 PHP 的配置文件。这种随便读入一个未经许可的配置文件的行为将可能会导致一个不可预知的错误。在 PHP 5.2 版本里已经将该特性移除，不再再在CWD（当前工作目录）里查找 php.ini 或php-cli.ini 文件了。

总结：

总体来说，从性能上 PHP 5.2 已经超越 PHP4.x 成为目前速度最快的版本，从语言及安全特性上也是无出其右。即便是 PHP4.x 有一些代码缓存工具（如 eAccelerator）可以提高性能，但目前也已经有 APC、X-Cache 等表示可以支持 5.2 版本（eAccelerator 可能还需要一段时间来完善）。虽然 APC 等在性能还略输于eAccelerator，但加上 PHP5.2 的种种优化措施，至少不会比 PHP4+eAccelerator 差到哪去更何况还有很要命的安全更新。既然如此，那我们还有什么理由不升级呢？同时我也推荐各大虚拟主机厂商将其服务器（至少是新增的服务器）更新为 PHP5.2 版本。在不增加性能消耗的基础上还能为客户提供更多的语言特性，同时也增强了产品的竞争力，何乐而不为呢？

让我们开始全面进入 PHP 5.2 的时代吧！

写在前面：最近一直在翻译《PHP 手册》中的《Zend API－深入 PHP 内核》一章，不过翻译终究是别人的东西，有些看法、做法即使和原作者不大相同那也得照翻。当然不能说自己所想的就是对的、好的，但的确有时是有很多疑问和想法，若是直接在译文中加入自己的看法恐怕不太合适，所以一直在找机会自己写一些这方面文章，以供以后回顾总结时的参考。这时恰逢《PHP&MORE》杂志抬爱，想邀稿在第七期或以后发表一些这类的文章，于是欣然应允。

这篇文章是属于入门型的，本是想给进行 PHP 扩展开发的朋友一些大致的参考，以便倒时不致于找不到下手的方向。但写着写着就感觉有点把握不住了。因为我是一个好奇心很强的人，喜欢刨根问底，探究底层。对于 PHP 扩展也是一样。我是拿自己当文章的第一个读者的，希望能把每个问题都描述清楚，很想全面铺开，结果越写就越觉得有很多地方没提到。但对于初次接触这方面的人来说说得太多似乎也不合适。于是经常处于这种矛盾的煎熬之中。经过几次权衡之后，终于敲出了下面的文章。

扩展 PHP

关于扩展 PHP，可谈的话题有很多，问题也有很多。在这无数的话题和问题中间，“为什么要对 PHP 进行扩展，PHP 扩展可以干什么” 这个问题也是话题无疑是最常也是最先被提到的。因此，本文第一个要谈的问题就是：为什么要对 PHP 进行扩展？

可以说，PHP 正是有了扩展才显得生机盎然。试想，如果 PHP 没有 GD扩展、没有了 MySQL 扩展，那将会变得多么无趣！因此，扩展 PHP 的一个主要目的就是想完成那些以前不可能完成的事情。想操作 Zip 文件？没问题！[1]（这个Zip 扩展已经有人在进行了，PHP 5.2 当中会默认启用该扩展。）想开发 3D 游戏？没问题！[2]（已经可以利用 PHP-GTK 开发出基本的程序）想对女朋友发短信？更没问题！：）只要你想得到，利用 PHP 扩展就可以做得到！ 除此之外，对 PHP 进行扩展的另一个主要目的就是用以提高程序性能。PHP 中的 “3 + 2″ 和 扩展二进制代码中的 “3 + 2″ 的执行速度显然不在同一个数量级。而对于那些应用更为复杂，运行条件更为苛刻的系统，将其某些逻辑和运算过程封装到一个 PHP 扩展就显得很有必要了。

既然扩展是如此的“无所不能”，那么编写一个扩展是否需要一个很高的门槛呢？

No！编写一个扩展是很容易的，只要具有一定的 C 语言基础就行。当然，若用其他语言进行开发也可以，但由于 PHP 自身就是利用 C 编写的，因此无论是在代码兼容性还是可学习性（PHP 源码包中自带了很多扩展的源代码，很有参考价值）上，C 语言都具有很大的优势。C++ 由于兼容C，也可以作为一种选择，但需要对代码的编译部分和其他一些地方做些技巧性的处理。

还有一个问题，跨平台这个问题怎么处理？在 Windows 和 Linux (或其他 xNix 平台)开发有什么不同？

没有什么不同。这是因为 C 语言本身就跨平台（当然跟 Java 那种跨平台的概念有所不同），采用 C 编写出来的代码可以在绝大多数机器、绝大多数操作系统上编译运行。但很明显，你不能在 Linux 的环境下去调用 Win32 API。所有的代码应该尽量采用 C 标准库去书写，若实在不可避免就应该采用一些宏定义去分开处理。笔者喜欢在 Windows 环境下开发，因此本文所举诸例皆为在 Windows 环境下的情况。但这并不碍大事，仅仅是习惯而已，代码还是一样的。

现在相信你已经对PHP 进行扩展有了一个大致的认识了，下面我们就来具体谈谈 PHP 扩展以及如何开发一个简单的扩展。

对PHP 进行的某项扩展（Extend）我们就称之为 PHP 的一个扩展（Extension）（有时也被人称之为模块：Module）。扩展有两类四种（我认为 PHP 手册上只有三种的分法是值得商榷的）。

按其二进制代码相对于PHP自身的位置不同，可以分为内建的（Build-in）和外部的（External）。所谓内建的是指该扩展在编译时被编译进了 PHP，调用该扩展的代码等就跟调用 PHP 原来自带的代码等毫无二致。而“外部的”扩展就是指该扩展被单独编译成一个模块，若想使用就必须使用 dl() 函数或者在 php.ini 中利用类似 “extension= xxx” 的指令手动加载。两者各有优缺。内建扩展被自然编译进 PHP 代码，调用时避免了加载过程，性能较外部扩展略强。其缺点就是与 PHP 代码结合度太高，一旦扩展有个风吹草动，你就不得不重新对 PHP 进行编译。而外部扩展的优缺点则恰好与内建扩展相反。

按其所处语言层次的不同，扩展可分为 PHP 扩展和 Zend 扩展。自 PHP4 开始，Andi Gutmans 和 Zeev Suraski 为 PHP 引入了 Zend 引擎（Zend Engine） 以便把 PHP 语言自身和 PHP 所提供一些外部功能区分开来。Zend 引擎负责处理 PHP 语言本身，假如你想给 PHP 语法引入一个新的操作符（比如“A bs B”表示变量 A 鄙视 变量 B）或者是想修改一下 PHP 本身的运行机制，那做一个 Zend 扩展就很合适。如果你的扩展只是想让 PHP 在上传时可以自动生成一个进度条图片，那这个扩展我们就称之为 PHP 扩展。用一句形象的话来说就是：Zend 扩展主内，PHP 扩展主外。

Zend 扩展的架构和 PHP 扩展的架构基本一样，只是处理层次的有所不同。由于 PHP 扩展不牵涉到 PHP 自身的内部架构，因此一般情况下，开发一个 PHP 扩展要比开发开发一个 Zend 扩展容易一些。MySQL 扩展，GD 扩展都是PHP 扩展，本文所举的例子也是一个 PHP 扩展。Zend 扩展常见的有 APC、ZendOptimizer等。

由于开发一个 Zend 扩展需要一定的 PHP 内部结构的认识，我们将会在先讨论一些预备知识之后再来谈 Zend 扩展的开发。

开发环境的搭建

首先我们需要一个 PHP 的源码包，这个可以到http://www.php.net/downloads.php 去下载，记得我们是要源码包（Complete Source Code）而不是PHP 的二进制代码包（Windows Binaries）。本文所采用是 PHP 5.1.6 的源码包。PHP4 与 PHP5 的PHP 扩展有稍许不同，在必要处我会提醒这一点的，因此您也可以采用 PHP 4.4.x 系列的源码包。

除此之外我们还需要一个 php5ts.lib （若用 PHP 4 的源码包则需要的是 php4ts.lib）的文件。这在PHP 二进制代码包的 dev 目录（php4ts.lib 则是直接放在二进制代码包的根目录）下可以找到。

将该源码包解压到某个目录（假定是D:\Work\PHP\work\php5，以后我们以 $PHP 指代该源码根目录），我们可以看到main、Zend、win32、TSRM、ext 等目录。在 ext 目录下有 ext_skel 和 ext_skel_win32.php 两个文件。Ext_skel 是在 xNix 环境下的一个用于构建PHP 扩展，生成 PHP 扩展框架的自动化脚本。由于是在 xNix 环境下使用的，并且使用方法也比较简单，故本文不再赘述。具体使用方法可参见源码包根目录（即 $PHP）下的README.EXT_SKEL 文件。ext_skel_win32.php 顾名思义是用来创建 Win32 环境下扩展框架的的脚本。这个脚本需要 Cygwin (http://www.cygwin.com/) 的支持。使用方法和ext_skel 大同小异。本文所采用的是第三种方法：使用 VC 的向导手动创建一个项目文件。这种方法好处就是不需要 Cygwin 的支持，但在编译该扩展的 xNix 版本时仍然需要通过ext_skel 来创建一个相应的框架。

我们在这里使用的 IDE 是 VC++ 2005 Express Edition 。如果你的扩展将来需要分发到更多的地方，建议你使用 VC++ 6.0，这样可增加一定的兼容性。PHP 扩展在 VC++ 6.0 和 VC++ 2005里面的操作都差不多，但在 VC++ 2005 中需要进行一些额外的设置。

现在让我们打开 VC++ 2005，在菜单中选择 【File】 -> 【New】 -> 【Project】 来创建这个扩展的项目文件。

在【项目类型(Project Types)】中选择“Virual C++”，项目【模版（Templates）】为“Win32 Project”。在本例中我们的扩展名字为 phpmore，位于 $PHP\ext目录下。

提示：虽然一个扩展项目的存放位置并没有具体规定，但放到 $PHP\ext 目录下是一个惯例，这会避免很多不必要的麻烦。

在出现的 【Win32 应用程序向导（Win32 Application Wizard）】中点击左面的【应用程序设置（Application Settings）】，设置【程序类型（Application Type）】为“DLL”，并且将其设置为【空项目（Empty Project）】。
点击【完成（Finish）】就创建了该扩展的项目文件。此时你应该会在 $PHP\ext\phpmore 目录下找到该扩展的“解决方案(solution)”文件。在$PHP\ext\phpmore\ phpmore 目录下找到扩展的“项目（Project）”文件。

提示：按照 VS 2005 的说法，一个“解决方案(solution)”是由多个“项目（Project）”组成的，因此产生这样的目录结构是十分合理的。但对 PHP 扩展而言，由于需要在各个系统平台下运行，如果把所有平台的项目文件都放在扩展的根目录下面，就会给人一种非常凌乱的感觉。一个值得推荐的解决方法就是为每个平台都建立一个目录，各自包含相应的项目文件，而把源代码文件（*.c 和 *.h 等）放在扩展根目录或其他一个单独的目录。本文为了简单叙述起见，不再额外处理，但在实际应用过程中请注意源代码目录的合理分配。

现在我们将扩展的源代码文件（phpmore.c 和 phpmore.h ，当然此时是空文件）新建/添加到 phpmore 扩展的项目文件当中。

提示：在 VC++ 2005 中添加源代码文件时默认的后缀名为 .cpp，此时需要主动为文件添加上 .c 的扩展名。否则 VC 的编译器会将其默认为 C++ 代码而进行编译（当然这种设置也是可以改变的），这样就可能会产生一些编译错误。

为了能够很方便的引用 PHP 代码的头文件以及对项目进行编译，我们还需要对项目文件进行一些设置。请通过菜单【项目(Project)】-> 【phpmore 属性(Properties)】进入项目的属性设置页。这里我们先对项目的【Release】版进行配置。见图四。

先转到【C++】属性的【General】页填入“Additional Include Directories”： $PHP;$PHP\main;$PHP\win32;$PHP\TSRM;$PHP\Zend。我们这里输入的绝对路径，但实际开发过程中最好填入相对路径。

再转到【C++】属性的【Preprocessor】页补充一些“Preprocessor Definitions”： ZEND_WIN32;PHP_WIN32;ZTS=1; ZEND_DEBUG=0; COMPILE_DL_PHPMORE 。前面3个是在 Win32 环境下开发所必加的预定义；ZEND_DEBUG=0表示扩展不创建为Debug 版本（因为现在是在配置Release 版本嘛～）；COMPILE_DL_PHPMORE 用于是否将本扩展编译为一个“外部扩展（定义见文首）”。

在【C++】属性里面还需要设置的有：【Code Generation】页的“运行库（Runtime Library）”请设置为“Multi-threaded DLL (/MD)”；【Advanced】页的“编译方式（Compile As）”请设置为“Compile as C Code (/TC)”

此外还需要在【连接器(Linker)】属性的【Input】页添加一个“Additional Dependencies”： php5ts.lib 。你可以把 php5ts.lib 放到一个 VC++ 能找到的地方，比如项目文件的目录。当然你若采用的是 PHP 4的源码包，请相应地把php5ts.lib 替换为 php4ts.lib 。

这样，整个扩展项目文件的Release 版本就配置好了。对于 Debug 版本可以有针对性的作一些改动。不过需要注意，一般的 PHP 二进制代码包不允许加载 Debug 版本的扩展，只有将 PHP 编译为 Debug 版本才能加载 Debug 版本的扩展。

提示：如果需要扩展在多种PHP版本中都可布署，那可以先设置一个基本配置（就像上例不设置 php5ts.lib），然后再创建一个继承自基本配置的新的配置－比如Release_PHP5－在这个 Release_PHP5 中额外设置一下 php5ts.lib 就可以了。有的扩展还不事先预定义 ZTS，而是额外再创建一个 Release_TS 的配置，道理是一样的。

OK，现在万事俱备，只欠编码了，让我们这就开始吧！

所有的扩展都大致由4个部分组成：引用相关的头文件、Zend 模块的声明与相关函数实现、get_module() 函数的实现以及导出函数的声明和实现。关于这几部分的详细说明，请看 PHP 手册中《Zend API：深入 PHP 内核》一章。笔者正在试译这几章，对英文理解有困难的朋友可以先到笔者的站点去看一下译文。

为了简单叙述起见，我先列出本文例子的代码：

phpmore.h :

#ifndef PHPMORE_H
    #define PHPMORE_H
    extern zend_module_entry phpmore_module_entry;
    #define phpext_phpmore_ptr &phpmore_module_entry

    /* declaration of functions to be exported */
    ZEND_FUNCTION(welcome_to_phpmore);
    PHP_MINFO_FUNCTION(phpmore);

    #define PHPMORE_VERSION "0.1.0"
#endif

phpmore.c :

#define _USE_32BIT_TIME_T 1
#include "php.h"
#include "phpmore.h"

zend_function_entry phpmore_functions[] =
{
    ZEND_FE(welcome_to_phpmore, NULL)
    {NULL, NULL, NULL}
};

zend_module_entry phpmore_module_entry =
{
    STANDARD_MODULE_HEADER,
    "PHP&More",
    phpmore_functions,
    NULL,
    NULL,
    NULL,
    NULL,
    PHP_MINFO(phpmore),
    PHPMORE_VERSION,
    STANDARD_MODULE_PROPERTIES
};

#if COMPILE_DL_PHPMORE
    ZEND_GET_MODULE(phpmore)
#endif

PHP_MINFO_FUNCTION(phpmore)
{
    php_info_print_table_start();
    php_info_print_table_header(2, "PHP&More", "enabled");
    php_info_print_table_row(2, "Version", PHPMORE_VERSION);
    php_info_print_table_end();
}

ZEND_FUNCTION(welcome_to_phpmore)
{
 zend_printf("Welcome to PHP&More!");
}

所有扩展都必须至少包含有 php.h ，这是一切的基础，因此必须首先在代码中引用（添加 #define _USE_32BIT_TIME_T 1 这一行是为了去掉 VC++ 2005 中 64 位时间格式的支持，在 VS.NET 2003 或 VC++ 6.0 中均无需这样做）。

接下来是扩展的 Zend 函数块的声明。定义了一个名为 phpmore_functions ，每一个元素都是一个 zend_function_entry 结构的 Zend 函数数组。该数组用来声明本扩展一共对外（即 PHP 脚本）提供了多少可用的（导出）函数。由于没有其他地方可以主动提供（导出）函数的个数，因此数组的最后一个元素必须为 {NULL, NULL, NULL}，以便 Zend Engine 可以获知函数数组的元素列表是否结束。

然后就是整个扩展模块的声明。这是一个扩展“最高”层次的声明。全方位地提供了 Zend Engine 所需要的各种信息。上面所声明的导出函数列表也仅仅是用来填充它的一个字段而已。除此之外，这个模块声明还负责提供扩展名称（就是将来在 phpinfo() 函数中出现的那个扩展的名字，本例为“PHP&More”）、导出函数列表（本例为phpmore_functions）、模块启动函数（PHP_MINIT_FUNCTION，在模块第一次加载时被调用，本例为 NULL）、模块关闭函数（PHP_MSHUTDOWN_FUNCTION，在模块卸载关闭时被调用，本例为 NULL）、请求启动函数（在每个请求启动时被调用，本例为 NULL）、请求关闭函数（PHP_RINIT_FUNCTION，在每个请求关闭时被调用，本例为 NULL）、模块信息函数（PHP_RSHUTDOWN_FUNCTION，用于在 phpinfo() 中显示扩展的信息，本例为“PHP_MINFO_FUNCTION(phpmore)”）和模块版本（本例为 PHPMORE_VERSION ，定义在 phpmore.h ）等其他信息。这几个模块函数的调用关系及顺序见图：

模块声明后面就是 get_module() 函数的实现。这个函数的声明没有手动写出，而是使用了一个宏 ZEND_GET_MODULE(phpmore) 来声明。这也是在扩展开发中常用的一种手段，我们应该尽力地去使用宏。get_module() 函数用于向 Zend Engine 报告这是个外部扩展，这也可以使得我们能够通过 dl() 函数来手动加载它。

剩下的两段代码便是我们前面声明函数的具体实现。一个是模块信息函数，一个是对外导出的 welcome_to_phpmore 函数。模块信息函数对外输出了本扩展的启用状态和版本号，而 welcome_to_phpmore 函数则在 PHP 脚本调用 welcome_to_phpmore() 时对外输出字符串“Welcome to PHP&More!”。

一个扩展的大致结构就是这样。简单编译后我们就得到了一个 phpmore.dll 的文件。相应更改更改 php.ini 及重新启动 Web 服务器后，就可以启用这个扩展了。

先祝贺《PHPer》发布创刊号！新生的事物总是孕育着无限希望，祝愿《PHPer》能够坚持办刊理念，成长为 PHP 中文杂志中的一朵奇葩～

《PHP&MORE》也是在“十月怀胎（这次可真的是十个月）”后终于发布了第七期。这一期她的专题是 LAMP 的优化。

这两本杂志各有不同的风格。《PHPer》主要面向初中级的 PHP 程序员，内容较为浅显。如果你对 PHP 准备入门或刚入门却不知怎么提高的话，那么这本杂志将会很适合您阅读。但这并非就是说整本杂志都是些入门级的文章，有些还是很有深度，值得进一步研究和探讨的。《PHP&MORE》基本上都是以专题的形式出现，阅读的对象相对专业一些。虽说有时出版周期过长，但所幸很多文章都值得长时间咀嚼。

光说没什么用，还是先下载下来看看吧～

查看《PHPer》创刊号

查看《PHP&MORE》第七期

btw：这两期杂志各有本人拙作一篇，欢迎砸砖，或者略去不看～:D

对于扩展来说，最重要的一件事就是如何接收和处理那些通过函数参数传递而来的数据。大多数扩展都是用来处理某些特定的输入数据（或者是根据参数来决定进行某些特定的动作），而函数的参数则是 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 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 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", &obj, my_ce, &d) == FAILURE) {
   return;
}

/* 取得一个对象或空值，再取得一个数组。如果传递进来一个空对象，则 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_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() 来得到。

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

int zend_parse_parameters_ex(int flags, int num_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_count,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 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 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 参数类型转换函数

图3.2　PHP 的数据交叉转换

在你的参数上使用这些函数可以确保传递给你的数据都是类型安全的。如果提供的类型不是需要的类型，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 有一点点认识。它的定义如下：

例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 结构

表3.6 Zend zvalue_value 结构

表3.7 Zend 变量类型

想访问一个长整型数，那你就访问 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", &parameter) == 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 本节不再赘述。