Zend API：深入 PHP 内核-php手册-php.cn

http://roygu.com/doc/blog/dive-to-php-core.html Zend API：深入 PHP 内核译序及目录译序 http://www.yAnbiN.org PHP 中文手册《Zend API: 深入PHP内核》目录摘要概述可扩展性源码布局自动构建系统开始创建扩展使用扩展故障处理关于模块代码的

http://roygu.com/doc/blog/dive-to-php-core.html

Zend API：深入 PHP 内核

译序及目录

译序

http://www.yAnbiN.org

PHP 中文手册《Zend API: 深入PHP内核》目录

摘要
概述
可扩展性
源码布局
自动构建系统
开始创建扩展
使用扩展
故障处理
关于模块代码的讨论
接收参数
创建变量
使用拷贝构造函数复制变量内容
返回函数值
信息输出
启动函数与关闭函数
调用用户函数
支持初始化文件php.ini
何去何从
参考：关于配置文件的一些宏
API 宏

(一)摘要

知者不言，言者不知。 ――老子《道德经》五十六章

有时候，单纯依靠 PHP “本身”是不行的。尽管普通用户很少遇到这种情况，但一些专业性的应用则经常需要将 PHP 的性能发挥到极致（这里的性能是指速度或功能）。由于受到 PHP 语言本身的限制，同时还可能不得不把庞大的库文件包含到每个脚本当中。因此，某些新功能并不是总能被顺利实现，所以我们必须另外寻找一些方法来克服 PHP 的这些缺点。

了解到了这一点，我们就应该接触一下 PHP 的心脏并探究一下它的内核－可以编译成 PHP 并让之工作的 C 代码－的时候了。

(二)概述

“扩展 PHP”说起来容易做起来难。PHP 现在已经发展成了一个具有数兆字节源代码的非常成熟的系统。要想深入这样的一个系统，有很多东西需要学习和考虑。在写这一章节的时候，我们最终决定采用“边学边做”的方式。这也许并不是最科学和专业的方式，但却应该是最有趣和最有效的一种方式。在下面的小节里，你首先会非常快速的学习到如何写一个虽然很基础但却能立即运行的扩展，然后将会学习到有关 Zend API 的高级功能。另外一个选择就是将其作为一个整体，一次性的讲述所有的这些操作、设计、技巧和诀窍等，并且可以让我们在实际动手前就可以得到一副完整的愿景。这看起来似乎是一个更好的方法，也没有死角，但它却枯燥无味、费时费力，很容易让人感到气馁。这就是我们为什么要采用非常直接的讲法的原因。

注意，尽管这一章会尽可能多讲述一些关于 PHP 内部工作机制的知识，但要想真的给出一份在任何时间任何情况下的PHP 扩展指南，那简直是不可能的。PHP 是如此庞大和复杂，以致于只有你亲自动手实践一下才有可能真正理解它的内部工作机制，因此我们强烈推荐你随时参考它的源代码来进行工作。

Zend 是什么？ PHP 又是什么？

Zend 指的是语言引擎，PHP 指的是我们从外面看到的一套完整的系统。这听起来有点糊涂，但其实并不复杂（见图3-1 PHP 内部结构图）。为了实现一个 WEB 脚本的解释器，你需要完成以下三个部分的工作：

解释器部分：负责对输入代码的分析、翻译和执行；
功能性部分：负责具体实现语言的各种功能（比如它的函数等等）；
接口部分：负责同 WEB 服务器的会话等功能。

Zend 包括了第一部分的全部和第二部分的局部，PHP 包括了第二部分的局部和第三部分的全部。他们合起来称之为 PHP 包。Zend 构成了语言的核心，同时也包含了一些最基本的 PHP 预定义函数的实现。PHP 则包含了所有创造出语言本身各种显著特性的模块。

图3-1 PHP 内部结构图

下面将要讨论PHP 允许在哪里扩展以及如何扩展。

(三)可扩展性

正如上图（图3-1 PHP 内部结构图）所示，PHP 主要以三种方式来进行扩展：外部模块，内建模块和 Zend 引擎。下面我们将分别讨论这些方式：

外部模块

外部模块可以在脚本运行时使用 dl() 函数载入。这个函数从磁盘载入一个共享对象并将它的功能与调用该函数的脚本进行绑定并使之生效。脚本终止后，这个外部模块将在内存中被丢弃。这种方式有利有弊，如下表所示：

优点	缺点
外部模块不需要重新对 PHP 进行编译。	共享对象在每次脚本调用时都需要对其进行加载，速度较慢。
PHP通过“外包”方式来让自身的体积保持很小。	附加的外部模块文件会让磁盘变得比较散乱。

综上所述，外部模块非常适合开发第三方产品，较少使用的附加的小功能或者仅仅是调试等这些用途。为了迅速开发一些附加功能，外部模块是最佳方式。但对于一些经常使用的、实现较大的，代码较为复杂的应用，那就有些得不偿失了。

内建模块

内建模块被直接编译进 PHP 并存在于每一个 PHP 处理请求当中。它们的功能在脚本开始运行时立即生效。和外部模块一样，内建模块也有一下利弊：

优点	缺点
无需专门手动载入，功能即时生效。	修改内建模块时需要重新编译PHP。
无需额外的磁盘文件，所有功能均内置在 PHP 二进制代码当中。	PHP 二进制文件会变大并且会消耗更多的内存。

Zend 引擎

当然，你也能直接在 Zend 引擎里面进行扩展。如果你需要在语言特性方面做些改动或者是需要在语言核心内置一些特别的功能，那么这就是一种很好的方式。但一般情况下应该尽力避免对 Zend 引擎的修改。这里面的改动会导致和其他代码的不兼容，而且几乎没有人会适应打过特殊补丁的 Zend 引擎。况且这些改动与主 PHP 源代码是不可分割的，因此就有可能在下一次的官方的源代码更新中被覆盖掉。因此，这种方式通常被认为是“不良的习惯”。由于使用极其稀少，本章将不再对此进行赘述。

(四)源码布局

在我们开始讨论具体编码这个话题前，你应该让自己熟悉一下 PHP 的源代码树以便可以迅速地对各个源文件进行定位。这也是编写和调试 PHP 扩展所必须具备的一种能力。

下表列出了一些主要目录的内容：

目录	内容
php-src	包含了PHP主源文件和主头文件；在这里你可以找到所有的 PHP API 定义、宏等内容。(重要). 其他的一些东西你也可以在这里找到。
php-src/ext	这里是存放动态和内建模块的仓库；默认情况下，这些就是被集成于主源码树中的“官方” PHP 模块。自 PHP 4.0开始，这些PHP标准扩展都可以编译为动态可载入的模块。(至少这些是可以的)。
php-src/main	这个目录包含主要的 PHP 宏和定义。 (重要)
php-src/pear	这个目录就是“PHP 扩展与应用仓库”的目录。包含了PEAR 的核心文件。
php-src/sapi	包含了不同服务器抽象层的代码。
TSRM	Zend 和 PHP的 “线程安全资源管理器” (TSRM) 目录。

除此之外，你也应该注意一下这些文件所包含的一些文件。举例来说，哪些文件与 Zend 执行器有关，哪些文件又为 PHP 初始化工作提供了支持等等。在阅读完这些文件之后，你还可以花点时间再围绕PHP包来看一些文件，了解一下这些文件和模块之间的依赖性――它们之间是如何依赖于别的文件又是如何为其他文件提供支持的。同时这也可以帮助你适应一下 PHP 创作者们代码的风格。要想扩展 PHP，你应该尽快适应这种风格。

扩展规范

Zend 是用一些特定的规范构建的。为了避免破坏这些规范，你应该遵循以下的几个规则：

1. 宏

几乎对于每一项重要的任务，Zend 都预先提供了极为方便的宏。在下面章节的图表里将会描述到大部分基本函数、结构和宏。这些宏定义大多可以在 Zend.h 和 Zend_API.h 中找到。我们建议您在学习完本节之后仔细看一下这些文件。（当然你也可以现在就阅读这些文件，但你可能不会留下太多的印象。）

2. 内存管理

资源管理仍然是一个极为关键的问题，尤其是对服务器软件而言。资源里最具宝贵的则非内存莫属了，内存管理也必须极端小心。内存管理在 Zend 中已经被部分抽象，而且你也应该坚持使用这些抽象，原因显而易见：由于得以抽象，Zend 就可以完全控制内存的分配。Zend 可以确定一块内存是否在使用，也可以自动释放未使用和失去引用的内存块，因此就可以避免内存泄漏。下表列出了一些常用函数：

函数	描述
emalloc()	用于替代 malloc()。
efree()	用于替代 free()。
estrdup()	用于替代 strdup()。
estrndup()	用于替代strndup()。速度要快于 estrdup() 而且是二进制安全的。如果你在复制之前预先知道这个字符串的长度那就推荐你使用这个函数。
ecalloc()	用于替代 calloc()。
erealloc()	用于替代 realloc()。

emalloc(), estrdup(), estrndup(), ecalloc(), 和 erealloc() 用于申请内部的内存，efree() 则用来释放这些前面这些函数申请的内存。e*() 函数所用到的内存仅对当前本地的处理请求有效，并且会在脚本执行完毕，处理请求终止时被释放。

Zend 还有一个线程安全资源管理器，这可以为多线程WEB 服务器提供更好的本地支持。不过这需要你为所有的全局变量申请一个局部结构来支持并发线程。但是因为在写本章内容时Zend 的线程安全模式仍未完成，因此我们无法过多地涉及这个话题。

3. 目录与文件函数

下列目录与文件函数应该在 Zend 模块内使用。它们的表现和对应的 C 语言版本完全一致，只是在线程级提供了虚拟目录的支持。

Zend 函数	对应的 C 函数
V_GETCWD()	getcwd()
V_FOPEN()	fopen()
V_OPEN()	open()
V_CHDIR()	chdir()
V_GETWD()	getwd()
V_CHDIR_FILE()	将当前的工作目录切换到一个以文件名为参数的该文件所在的目录。
V_STAT()	stat()
V_LSTAT()	lstat()

4. 字符串处理

在 Zend 引擎中，与处理诸如整数、布尔值等这些无需为其保存的值而额外申请内存的简单类型不同，如果你想从一个函数返回一个字符串，或往符号表新建一个字符串变量，或做其他类似的事情，那你就必须确认是否已经使用上面的 e*() 等函数为这些字符串申请内存。（你可能对此没有多大的感觉。无所谓，现在你只需在脑子里有点印象即可，我们稍后就会再次回到这个话题）

5. 复杂类型

像数组和对象等这些复杂类型需要另外不同的处理。它们被出存在哈希表中，Zend 提供了一些简单的 API 来操作这些类型。

(五)自动构建系统

PHP 提供了一套非常灵活的自动构建系统（automatic build system），它把所有的模块均放在 Ext 子目录下。每个模块除自身的源代码外，还都有一个用来配置该扩展的 config.m4 文件（详情请参见http://www.gnu.org/software/m4/manual/m4.html）。

包括 .cvsignore 在内的所有文件都是由位于 Ext 目录下的 ext_skel 脚本自动生成的，它的参数就是你想创建模块的名称。这个脚本会创建一个与模块名相同的目录，里面包含了与该模块对应的一些的文件。

下面是操作步骤：

:~/cvs/php4/ext:> ./ext_skel --extname=my_module

Nach dem Login kopieren

响应如下：

Creating directory my_module
Creating basic files: config.m4 .cvsignore my_module.c php_my_module.h CREDITS EXPERIMENTAL tests/001.phpt my_module.php [done].

To use your new extension, you will have to execute the following steps:
1. $ cd ..
2. $ vi ext/my_module/config.m4
3. $ ./buildconf
4. $ ./configure --[with|enable]-my_module
5. $ make
6. $ ./php -f ext/my_module/my_module.php
7. $ vi ext/my_module/my_module.c
8. $ make

Repeat steps 3-6 until you are satisfied with ext/my_module/config.m4 and step 6 confirms that your module is compiled into PHP. Then, start writing code and repeat the last two steps as often as necessary.

Nach dem Login kopieren

这些指令就会生成前面所说的那些文件。为了能够在自动配置文件和构建程序中包含新增加的模块，你还需要再运行一次 buildconf 命令。这个命令会通过搜索 Ext 目录和查找所有 config.m4 文件来重新生成 configure 脚本。默认情况下的的 config.m4 文件如例 3-1 所示，看起来可能会稍嫌复杂：

例3.1 默认的 config.m4 文件

dnl $Id: build.xml,v 1.1 2005/08/21 16:27:06 goba Exp $
dnl config.m4 for extension my_module
dnl Comments in this file start with the string 'dnl'.
dnl Remove where necessary. This file will not work
dnl without editing.

dnl If your extension references something external, use with:

dnl PHP_ARG_WITH(my_module, for my_module support, dnl Make sure that the comment is aligned:
dnl [ --with-my_module Include my_module support])

dnl Otherwise use enable:

dnl PHP_ARG_ENABLE(my_module, whether to enable my_module support,
dnl Make sure that the comment is aligned:
dnl [ --enable-my_module Enable my_module support])

if test $PHP_MY_MODULE != "no"; then
dnl Write more examples of tests here...

dnl # --with-my_module -> check with-path
dnl SEARCH_PATH = /usr/local /usr # you might want to change this
dnl SEARCH_FOR=/include/my_module.h you most likely want to change this
dnl if test -r $PHP_MY_MODULE/; then # path given as parameter
dnl MY_MODULE_DIR=$PHP_MY_MODULE
dnl else # search default path list
dnl AC_MSG_CHECKING([for my_module files in default path])
dnl for i in $SEARCH_PATH ; do
dnl if test -r $i/$SEARCH_FOR; then
dnl MY_MODULE_DIR=$i
AC_MSG_RESULT(found in $i)
dnl fi
dnl done
dnl fi
dnl
dnl if test -z "$MY_MODULE_DIR"; then
dnl AC_MSG_RESULT([not found])
dnl AC_MSG_ERROR([Please reinstall the my_module distribution])
dnl fi

dnl # --with-my_module -> add include path
dnl PHP_ADD_INCLUDE($MY_MODULE_DIR/include)

dnl # --with-my_module -> chech for lib and symbol presence
dnl LIBNAME=my_module # you may want to change this
dnl LIBSYMBOL=my_module # you most likely want to change this
dnl PHP_CHECK_LIBRARY($LIBNAME,$LIBSYMBOL,
dnl [ dnl PHP_ADD_LIBRARY_WITH_PATH($LIBNAME, $MY_MODULE_DIR/lib, MY_MODULE_SHARED_LIBADD)
dnl AC_DEFINE(HAVE_MY_MODULELIB,1,[ ])
dnl ],[
dnl AC_MSG_ERROR([wrong my_module lib version or lib not found])
dnl ],[
dnl -L$MY_MODULE_DIR/lib -lm -ldl
dnl ])
dnl
dnl PHP_SUBST(MY_MODULE_SHARED_LIBADD)

PHP_NEW_EXTENSION(my_module, my_module.c, $ext_shared)
fi

Nach dem Login kopieren

如果你不太熟悉 M4 文件（现在毫无疑问是熟悉 M4 文件的大好时机），那么就可能会有点糊涂。但是别担心，其实非常简单。

注意：凡是带有 dnl 前缀的都是注释，注释是不被解析的。

config.m4 文件负责在配置时解析 configure 的命令行选项。这就是说它将检查所需的外部文件并且要做一些类似配置与安装的任务。

默认的配置文件将会在 configure 脚本中产生两个配置指令：--with-my_module 和 --enable-my_module。当需要引用外部文件时使用第一个选项（就像用 --with-apache 指令来引用 Apache 的目录一样）。第二个选项可以让用户简单的决定是否要启用该扩展。不管你使用哪一个指令，你都应该注释掉另外一个。也就是说，如果你使用了 --enable-my_module，那就应该去掉--with-my_module。反之亦然。

默认情况下，通过 ext_skel 创建的 config.m4 都能接受指令，并且会自动启用该扩展。启用该扩展是通过 PHP_EXTENSION 这个宏进行的。如果你要改变一下默认的情况，想让用户明确的使用 --enable-my_module 或 --with-my_module 指令来把扩展包含在 PHP 二进制文件当中，那么将 if test "$PHP_MY_MODULE" != "no"改为if test "$PHP_MY_MODULE" == "yes"即可。

if test "$PHP_MY_MODULE" == "yes"; then dnl
Action.. PHP_EXTENSION(my_module, $ext_shared)
fi

Nach dem Login kopieren

这样就会导致在每次重新配置和编译 PHP 时都要求用户使用 --enable-my_module 指令。

另外请注意在修改 config.m4 文件后需要重新运行 buildconf 命令。

(六)开始创建扩展

我们先来创建一个非常简单的扩展，这个扩展除了一个将其整形参数作为返回值的函数外几乎什么都没有。下面（“例3-2 一个简单的扩展”）就是这个样例的代码：

例3.2 一个简单的扩展

/* include standard header */
#include "php.h"

/* declaration of functions to be exported */
ZEND_FUNCTION(first_module);

/* compiled function list so Zend knows what‘s in this module */
zend_function_entry firstmod_functions[] =
{
    ZEND_FE(first_module, NULL)
    {NULL, NULL, NULL}
};

/* compiled module information */
zend_module_entry firstmod_module_entry =
{
    STANDARD_MODULE_HEADER,
    "First Module",
    firstmod_functions,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    NO_VERSION_YET,
    STANDARD_MODULE_PROPERTIES
};

/* implement standard "stub" routine to introduce ourselves to Zend */
#if COMPILE_DL_FIRST_MODULE
ZEND_GET_MODULE(firstmod)
#endif

/* implement function that is meant to be made available to PHP */
ZEND_FUNCTION(first_module)
{
    long parameter;

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

    RETURN_LONG(parameter);
}

Nach dem Login kopieren

这段代码已经包含了一个完整的 PHP 模块。稍后我们会详细解释这段代码，现在让我们先讨论一下构建过程。（在我们讨论 API 函数前，这可以让心急的人先实验一下。）

模块的编译

模块的编译基本上有两种方法：

在 Ext 目录内使用“make” 机制，这种机制也可以编译出动态可加载模块。
手动编译源代码。

第一种方法明显受到人们的偏爱。自 PHP 4.0 以来，这也被标准化成了一个的复杂的构建过程。这种复杂性也导致了难于被理解这个缺点。在本章最后我们会更详细的讨论这些内容，但现在还是让我们使用默认的 make 文件吧。

第二种方法很适合那些（因为某种原因而）没有完整 PHP 源码树的或者是很喜欢敲键盘的人。虽然这些情况是比较罕见，但为了内容的完整性我们也会介绍一下这种方法。

使用 make 进行编译

为了能够使用这种标准机制流程来编译这些代码，让我们把它所有的子目录都复制到 PHP 源码树的 Ext 目录下。然后运行 buildconf 命令，这将会创建一个新的包含了与我们的扩展相对应的选项的 configure 脚本。默认情况下，样例中的所有代码都是未激活的，因此你不用担心会破坏你的构建程序。在 buildconf 执行完毕后，再使用 configure --help 命令就会显示出下面的附加模块：

--enable-array_experiments BOOK: Enables array experiments
--enable-call_userland BOOK: Enables userland module
--enable-cross_conversion BOOK: Enables cross-conversion module
--enable-first_module BOOK: Enables first module
--enable-infoprint BOOK: Enables infoprint module
--enable-reference_test BOOK: Enables reference test module
--enable-resource_test BOOK: Enables resource test module
--enable-variable_creation BOOK: Enables variable-creation module

Nach dem Login kopieren

前面样例（“例3-2 一个简单的扩展”）中的模块（first_module）可以使用 --enable-first_module 或 enable-first_module=yes 来激活。

手动编译

手动编译需要运行以下命令：

动作	命令
编译	cc -fpic -DCOMPILE_DL_FIRST_MODULE=1 -I/usr/local/include -I. -I.. -I../Zend -c -o
连接	cc -shared -L/usr/local/lib -rdynamic -o

编译命令只是简单的让编译器产生一些中间代码(不要忽略了--fpic 参数)，然后又定义了COMPILE_DL 常量来通知代码这是要编译为一个动态可加载的模块（通常用来测试，我们稍后会讨论它）。这些选项后面是一些编译这些源代码所必须包含的库文件目录。
注意：
本例中所有 include 的路径都是都是 Ext 目录的相对路径。如果您是在其他目录编译的这些源文件，那么还要相应的修改路径名。编译所需要的目录有 PHP 目录，Zend 目录和模块所在的目录（如果有必要的话）。
连接命令也是一个非常简单的把模块连接成一个动态模块的命令。

你可以在编译指令中加入优化选项，尽管这些已经在样例中忽略了（不过你还是可以从前面讨论的 make 模版文件中发现一些）。

注意：
手动将模块静态编译和连接到 PHP 二进制代码的指令很长很长，因此我们在这里不作讨论。（手动输入那些指令是很低效的。）

(七)使用扩展

根据你所选择的不同的构建过程，你要么把扩展编译进一个新的PHP 的二进制文件，然后再连接到 Web 服务器（或以CGI 模式运行），要么将其编译成一个 .so （共享库）文件。如果你将上面的样例文件 first_module.c 编译成了一个共享库，那么编译后的文件应该是 first_module.so。要想使用它，你就必须把他复制到一个 PHP 能访问到的地方。如果仅仅是为了测试的话，简单起见，你可以把它复制到你的 htdocs 目录下，然后用“例3.3 first_module.so 的一个测试文件”中的代码来进行一下测试。如果你将其直接编译编译进 PHP 二进制文件的话，那就不用调用 dl() 函数了，因为这个模块的函数在脚本一开始运行就生效了。

警告：
为了安全起见，你不应该将你的动态模块放入一个公共目录。即使是一个简单的测试你可以那么做，那也应该把它放进产品环境中的一个隔离的目录。

例3.3 first_module.so 的一个测试文件

<?php // remove next comment if necessary
// dl("first_module.so");
$param = 2
$return = first_module($param);
print("We sent '$param' and got '$return'");
?>

Nach dem Login kopieren

调用这个测试文件，结果应该输出为：

We sent '2' and got '2'。

若有需要，你可以调用 dl() 函数来载入一个动态可加载模块。这个函数负责寻找指定的共享库并进行加载使其函数在 PHP 中生效。这个样例模块仅输出了一个函数 first_module()，这个函数仅接受一个参数，并将其转换为整数作为函数的结果返回。

如果你已经进行到了这一步，那么，恭喜你，你已经成功创建了你的第一个 PHP 扩展！

(八)故障处理

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

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

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

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

模块结构

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

包含头文件(引入所需要的宏、API定义等)；
声明导出函数(用于 Zend 函数块的声明)；
声明 Zend 函数块；
声明 Zend 模块；
实现 get_module() 函数；
实现导出函数。

包含头文件

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

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

声明导出函数

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

ZEND_FUNCTION ( my_function );

Nach dem Login kopieren

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

void zif_my_function ( INTERNAL_FUNCTION_PARAMETERS );

Nach dem Login kopieren

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

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

Nach dem Login kopieren

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

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

表3.1 PHP 调用函数的 Zend 参数

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

声明 Zend 函数块

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

例3.4 zend_function_entry 的内部声明

typedef struct _zend_function_entry {
    char *fname;
    void (*handler)(INTERNAL_FUNCTION_PARAMETERS);
    unsigned char *func_arg_types;
} zend_function_entry;

Nach dem Login kopieren

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

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

<pre class="brush:php;toolbar:false">zend_function_entry firstmod_functions[] =
{
    ZEND_FE(first_module, NULL)
    {NULL, NULL, NULL}
};

Nach dem Login kopieren

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

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

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

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

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

表3.2 可用来定义函数的宏

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

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

声明 Zend 模块

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

例3.5 zend_module_entry 的内部声明

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

Nach dem Login kopieren

字段	说明
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_entry firstmod_module_entry =
{
    STANDARD_MODULE_HEADER,
    "First Module",
    firstmod_functions,
    NULL, NULL, NULL, NULL, NULL,
    NO_VERSION_YET,
    STANDARD_MODULE_PROPERTIES,
};

Nach dem Login kopieren

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

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

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

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

实现 get_module() 函数

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

#if COMPILE_DL_FIRSTMOD
ZEND_GET_MODULE(firstmod)
#endif

Nach dem Login kopieren

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

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

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

实现导出函数

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

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

Nach dem Login kopieren

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

小结

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

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

(十)接收参数

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

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

取得参数数量

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

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

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

Nach dem Login kopieren

如果没有为该函数传入两个参数，那么就会退出该函数并且发出一个错误消息。在这段代码中我们使用了一个工具宏：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; }

Nach dem Login kopieren

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

取回参数

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

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

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

Nach dem Login kopieren

第一个参数 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

Nach dem Login kopieren

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

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

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, ?m) == 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;
}

Nach dem Login kopieren

注意，在最后的一个例子中，我们直接用了数值 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, ...);

Nach dem Login kopieren

这个标志（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;
}

Nach dem Login kopieren

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

以前的老式的获取参数的的方法（不推荐）

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

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

Nach dem Login kopieren

所有的参数都存储在一个二次指向的 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;
}

Nach dem Login kopieren

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  4)
{
    WRONG_PARAM_COUNT;
}

/* 参数个数正确，开始接收。 */
if(zend_get_parameters_array_ex(argument_count, parameter_array) != SUCCESS)
{
    WRONG_PARAM_COUNT;
}

Nach dem Login kopieren

让我们来看看这几行代码。首先代码检查了传入参数的个数，确保在我们可接受的范围内；然后就调用 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 <p><br> </p><p><code><span>fsockopen()</span></code> 可以接收 2－5 个参数。在必需的变量声明之后便开始检查参数的数量范围。然后在一个 <code><span>switch</span></code> 语句中使用了贯穿（fall-through）法来处理这些的参数。这个 <code><span>switch</span></code> 语句首先处理最大的参数个数（即 5），随后依次处理了参数个数为 4 和 3 的情况，最后用 <code><span>break</span></code> 关键字跳出 <code><span>switch</span></code> 来忽略对其他情况下参数（也就是只含有 2 个参数情况）的处理。这样在经过 <code><span>switch</span></code> 处理之后，就开始处理参数个数为最小时（即 2）的情况。</p><p>这种像楼梯一样的多级处理方法可以帮助我们很方便地处理一些可变参数。</p><h4>存取参数</h4><p>为了存取一些参数，让每个参数都具有一个明确的（C）类型是很有必要的。但 PHP 是一种动态语言，PHP 从不做任何类型检查方面的工作，因此不管你想不想，调用者都可能会把任何类型的数据传到你的函数里。比如说，如果你想接收一个整数，但调用者却可能会给你传递个数组，反之亦然 － PHP 可不管这些的。</p><p>为了避免这些问题，你就必须用一大套 API 函数来对传入的每一个参数都做一下强制性的类型转换。（见表3.4 参数类型转换函数）</p><blockquote><p>注意：<br>所有的参数转换函数都以一个 <code><span>**zval</span></code> 来作为参数。</p></blockquote><p>表3.4 参数类型转换函数 </p>

Nach dem Login kopieren

函数	说明
convert_to_boolean_ex()	强制转换为布尔类型。若原来是布尔值则保留，不做改动。长整型值0、双精度型值0.0、空字符串或字符串‘0’还有空值 NULL