PHP Extension的开发基础
摘要&引言
PHP是当前应用非常广泛的一门语言，从国外的Facebook、Twitter到国内的淘宝、腾讯、百度再到互联网上林林总总的各种大中小型网站 都能见到它的身影。PHP的成功，应该说很大程度上依赖于其开放的扩展API机制和丰富的扩展组件（PHP Extension），正是这些扩展组件使得PHP从各种数据库操作到XML、JSON、加密、文件处理、图形处理、Socket等领域无所不能。有时候 开发人员可能需要开发自己的PHP扩展，当前PHP5的扩展机制是基于Zend API的，Zend API提供了丰富的接口和宏定义，加上一些实用工具，使得PHP扩展开发起来难度并不算特别大。本文将介绍关于PHP扩展组件开发的基本知识，并通过一个 实例展示开发PHP扩展的基本过程。
PHP扩展组件的开发过程在Unix和Windows环境下有所不同，但基本是互通的，本文将基于Unix环境（具体使用Linux）。阅读本文需 要简单了解Unix环境、PHP和C语言的一些基础知识，只要简单了解就行，我会尽量不涉及太过具体的操作系统和语言特性，并在必要的地方加以解释，以便 读者阅读。
本文的具体开发环境为Ubuntu 10.04 + PHP 5.3.3。
下载PHP源代码
要开发PHP扩展，第一步要下载PHP源代码，因为里面有开发扩展需要的工具。我下载的是PHP最新版本5.3.3，格式为tar.bz2压缩包。下载地址为：http://cn.php.net/get/php-5.3.3.tar.bz2/from/a/mirror。
下载后，将源代码移动到合适的目录并解压。解压命令为：
tar -jxvf 源码包名称tar -zxvf 源码包名称解压后，在源代码目录中有个ext目录，这里便是和PHP扩展有关的目录。进入目录后用ls查看，可以看到许多已经存在的扩展。下图是在我的环境下查看的结果：
其中蓝色的均是扩展包目录，其中可以看到我们很熟悉的mysql、iconv和gd等等。而ext_skel是Unix环境下用于自动生成PHP扩展框架的脚本工具，后面我们马上会用到，ext_skel_win32.php是windows下对应的脚本。
开发自己的PHP扩展——say_hello
下面我们开发一个PHP扩展：say_hello。这个扩展很简单，只是接受一个字符串参数，然后输出“Hello xxx!”。这个例子只是为了介绍PHP扩展组件的开发流程，不承担实际功能。
生成扩展组件框架
PHP的扩展组件开发目录和文件是有固定组织结构的，你可以随便进入一个已有扩展组件目录，查看其所有文件，我想你一定眼花缭乱了。当然你可以选择 手工完成框架的搭建，不过我相信你更希望有什么东西来帮你完成。上文提到的ext_skel脚本就是用来自动构建扩展包框架的工具。ext_skel的完 整命令为：
ext_skel --extname=module [--proto=file] [--stubs=file] [--xml[=file]] [--skel=dir] [--full-xml] [--no-help]
作为初学者，我们不必了解所有命令参数，实际上，大多数情况下只需要提供第一个参数就可以了，也就是扩展模块的名字。因此，我们在ext目录中键入如下命令：
./ext_skel --extname=say_hello
（如果你希望详细了解ext_skel的各项命令参数，请参考这里）
这时再用ls查看，会发现多了一个“say_hello”目录，进入这个目录，会发现ext_skel已经为我们建立好了say_hello的基本框架，如下图：
如果你懒得弄清楚PHP扩展包目录结构的全部内容，那么里面有三个文件你必须注意：
config.m4：这是Unix环境下的Build System配置文件，后面将会通过它生成配置和安装。
php_say_hello.h：这个文件是扩展模块的头文件。遵循C语言一贯的作风，这个里面可以放置一些自定义的结构体、全局变量等等。
say_hello.c：这个就是扩展模块的主程序文件了，最终的扩展模块各个函数入口都在这里。当然，你可以将所有程序代码都塞到这里面，也可以遵循模块化思想，将各个功能模块放到不同文件中。
下面的内容主要围绕这三个文件展开。
Unix Build System配置
开发PHP扩展组件的第一步不是写实现代码，而是要先配置好Build System选项。由于我们是在Linux下开发，所以这里的配置主要与config.m4有关。
关于Build System配置这一块，要是写起来能写一大堆，而且与Unix系统很多东西相关，就算我有兴趣写估计大家也没兴趣看，所以这里我们从略，只拣关键地方说一下，关于config.m4更多细节可以参考这里。
打开生成的config.m4文件，内容大致如下：
1 dnl $Id$
2 dnl config.m4 for extension say_hello
3
4 dnl Comments in this file start with the string 'dnl'.
5 dnl Remove where necessary. This file will not work
6 dnl without editing.
7
8 dnl If your extension references something external, use with:
9
10 dnl PHP_ARG_WITH(say_hello, for say_hello support,
11 dnl Make sure that the comment is aligned:
12 dnl [ --with-say_hello Include say_hello support])
13
14 dnl Otherwise use enable:
15
16 dnl PHP_ARG_ENABLE(say_hello, whether to enable say_hello support,
17 dnl Make sure that the comment is aligned:
18 dnl [ --enable-say_hello Enable say_hello support])
19
20 if test "$PHP_SAY_HELLO" != "no"; then
21 dnl Write more examples of tests here...
22
23 dnl # --with-say_hello -> check with-path
24 dnl SEARCH_PATH="/usr/local /usr" # you might want to change this
25 dnl SEARCH_FOR="/include/say_hello.h" # you most likely want to change this
26 dnl if test -r $PHP_SAY_HELLO/$SEARCH_FOR; then # path given as parameter
27 dnl SAY_HELLO_DIR=$PHP_SAY_HELLO
28 dnl else # search default path list
29 dnl AC_MSG_CHECKING([for say_hello files in default path])
30 dnl for i in $SEARCH_PATH ; do
31 dnl if test -r $i/$SEARCH_FOR; then
32 dnl SAY_HELLO_DIR=$i
33 dnl AC_MSG_RESULT(found in $i)
34 dnl fi
35 dnl done
36 dnl fi
37 dnl
38 dnl if test -z "$SAY_HELLO_DIR"; then
39 dnl AC_MSG_RESULT([not found])
40 dnl AC_MSG_ERROR([Please reinstall the say_hello distribution])
41 dnl fi
42
43 dnl # --with-say_hello -> add include path
44 dnl PHP_ADD_INCLUDE($SAY_HELLO_DIR/include)
45
46 dnl # --with-say_hello -> check for lib and symbol presence
47 dnl LIBNAME=say_hello # you may want to change this
48 dnl LIBSYMBOL=say_hello # you most likely want to change this
49
50 dnl PHP_CHECK_LIBRARY($LIBNAME,$LIBSYMBOL,
51 dnl [
52 dnl PHP_ADD_LIBRARY_WITH_PATH($LIBNAME, $SAY_HELLO_DIR/lib, SAY_HELLO_SHARED_LIBADD)
53 dnl AC_DEFINE(HAVE_SAY_HELLOLIB,1,[ ])
54 dnl ],[
55 dnl AC_MSG_ERROR([wrong say_hello lib version or lib not found])
56 dnl ],[
57 dnl -L$SAY_HELLO_DIR/lib -lm
58 dnl ])
59 dnl
60 dnl PHP_SUBST(SAY_HELLO_SHARED_LIBADD)
61
62 PHP_NEW_EXTENSION(say_hello, say_hello.c, $ext_shared)
63 fi
不要看这么多，因为所有以“dnl”开头的全是注释，所以真正起作用没几行。这里需要配置的只有下面几行：
1 dnl If your extension references something external, use with:
2
3 dnl PHP_ARG_WITH(say_hello, for say_hello support,
4 dnl Make sure that the comment is aligned:
5 dnl [ --with-say_hello Include say_hello support])
6
7 dnl Otherwise use enable:
8
9 dnl PHP_ARG_ENABLE(say_hello, whether to enable say_hello support,
10 dnl Make sure that the comment is aligned:
11 dnl [ --enable-say_hello Enable say_hello support])
我想大家也都能看明白，意思就是“如果你的扩展引用了外部组件，使用…，否则使用…”。我们的say_hello扩展并没有引用外部组件，所以将“Otherwise use enable”下面三行的“dnl”去掉，改为：
1 dnl Otherwise use enable:
2
3 PHP_ARG_ENABLE(say_hello, whether to enable say_hello support,
4 Make sure that the comment is aligned:
5 [ --enable-say_hello Enable say_hello support])
保存，这样关于Build System配置就大功告成了。
PHP Extension及Zend_Module结构分析
以上可以看成是为开发PHP扩展而做的准备工作，下面就要编写核心代码了。上文说过，编写PHP扩展是基于Zend API和一些宏的，所以如果要编写核心代码，我们首先要弄清楚PHP Extension的结构。因为一个PHP Extension在C语言层面实际上就是一个zend_module_entry结构体，这点可以从“php_say_hello.h”中得到证实。打 开“php_say_hello.h”，会看到里面有怎么一行：
extern zend_module_entry say_hello_module_entry;
say_hello_module_entry就是say_hello扩展的C语言对应元素，而关于其类型zend_module_entry的定义可以 在PHP源代码的“Zend/zend_modules.h”文件里找到，下面代码是zend_module_entry的定义：
1 typedef struct _zend_module_entry zend_module_entry;
2
3 struct _zend_module_entry {
4 unsigned short size;
5 unsigned int zend_api;
6 unsigned char zend_debug;
7 unsigned char zts;
8 const struct _zend_ini_entry *ini_entry;
9 const struct _zend_module_dep *deps;
10 const char *name;
11 const struct _zend_function_entry *functions;
12 int (*module_startup_func)(INIT_FUNC_ARGS);
13 int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
14 int (*request_startup_func)(INIT_FUNC_ARGS);
15 int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
16 void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
17 const char *version;
18 size_t globals_size;
19 #ifdef ZTS
20 ts_rsrc_id* globals_id_ptr;
21 #else
22 void* globals_ptr;
23 #endif
24 void (*globals_ctor)(void *global TSRMLS_DC);
25 void (*globals_dtor)(void *global TSRMLS_DC);
26 int (*post_deactivate_func)(void);
27 int module_started;
28 unsigned char type;
29 void *handle;
30 int module_number;
31 char *build_id;
32 };
这个结构体可能看起来会让人有点头疼，不过我还是要解释一下里面的内容。因为这就是PHP Extension的原型，如果不搞清楚，就没法开发PHP Extension了。当然，我就不一一对每个字段进行解释了，只拣关键的、这篇文章会用到的字段说，因为许多字段并不需要我们手工填写，而是可以使用某 些预定义的宏填充。
第7个字段“name”，这个字段是此PHP Extension的名字，在本例中就是“say_hello”。
第8个字段“functions”，这个将存放我们在此扩展中定义的函数的引用，具体结构不再分析，有兴趣的朋友可以阅读_zend_function_entry的源代码。具体编写代码时这里会有相应的宏。
第9-12个字段分别是四个函数指针，这四个函数会在相应时机被调用，分别是“扩展模块加载时”、“扩展模块卸载时”、“每个请求开始时”和“每个请求结束时”。这四个函数可以看成是一种拦截机制，主要用于相应时机的资源分配、释放等相关操作。
第13个字段“info_func”也是一个函数指针，这个指针指向的函数会在执行phpinfo()时被调用，用于显示自定义模块信息。
第14个字段“version”是模块的版本。
（关于zend_module_entry更详尽的介绍请参考这里)。
介绍完以上字段，我们可以看看“say_hello.c”中自动生成的“say_hello_module_entry”框架代码了。
1 /* {{{ say_hello_module_entry
2 */
3 zend_module_entry say_hello_module_entry = {
4 #if ZEND_MODULE_API_NO >= 20010901
5 STANDARD_MODULE_HEADER,
6 #endif
7 "say_hello",
8 say_hello_functions,
9 PHP_MINIT(say_hello),
10 PHP_MSHUTDOWN(say_hello),
11 PHP_RINIT(say_hello), /* Replace with NULL if there's nothing to do at request start */
12 PHP_RSHUTDOWN(say_hello), /* Replace with NULL if there's nothing to do at request end */
13 PHP_MINFO(say_hello),
14 #if ZEND_MODULE_API_NO >= 20010901
15 "0.1", /* Replace with version number for your extension */
16 #endif
17 STANDARD_MODULE_PROPERTIES
18 };
19 /* }}} */
首先，宏“STANDARD_MODULE_HEADER”会生成前6个字段，“STANDARD_MODULE_PROPERTIES ”会生成“version”后的字段，所以现在我们还不用操心。而我们关心的几个字段，也都填写好或由宏生成好了，并且在“say_hello.c”的相 应位置也生成了几个函数的框架。这里要注意，几个宏的参数均为“say_hello”，但这并不表示几个函数的名字全为“say_hello”，C语言中 也不可能存在函数名重载机制。实际上，在开发PHP Extension的过程中，几乎处处都要用到Zend里预定义的各种宏，从全局变量到函数的定义甚至返回值，都不能按照“裸写”的方式来编写C语言，这 是因为PHP的运行机制可能会导致命名冲突等问题，而这些宏会将函数等元素变换成一个内部名称，但这些对程序员都是透明的（除非你去阅读那些宏的代码）， 我们通过各种宏进行编程，而宏则为我们处理很多内部的东西。
写到这里，我们的任务就明了了：第一，如果需要在相应时机处理一些东西，那么需要填充各个拦截函数内容；第二，编写say_hello的功能函数，并将引用添加到say_hello_functions中。
编写phpinfo()回调函数
因为say_hello扩展在各个生命周期阶段并不需要做操作，所以我们只编写info_func的内容，上文说过，这个函数将在phpinfo()执行时被自动调用，用于显示扩展的信息。编写这个函数会用到四个函数：
php_info_print_table_start()——开始phpinfo表格。无参数。
php_info_print_table_header()——输出表格头。第一个参数是整形，指明头的列数，然后后面的参数是与列数等量的(char*)类型参数用于指定显示的文字。
php_info_print_table_row()——输出表格内容。第一个参数是整形，指明这一行的列数，然后后面的参数是与列数等量的(char*)类型参数用于指定显示的文字。
php_info_print_table_end()——结束phpinfo表格。无参数。
下面是“say_hello.c”中需要编写的info_func的具体代码：
1 /* {{{ PHP_MINFO_FUNCTION
2 */
3 PHP_MINFO_FUNCTION(say_hello)
4 {
5 php_info_print_table_start();
6 php_info_print_table_header(2, "say_hello support", "enabled");
7 php_info_print_table_row(2, "author", "Zhang Yang"); /* Replace with your name */
8 php_info_print_table_end();
9
10 /* Remove comments if you have entries in php.ini
11 DISPLAY_INI_ENTRIES();
12 */
13 }
14 /* }}} */
可以看到我们编写了两行内容、组件是否可用以及作者信息。
编写核心函数
编写核心函数，总共分为三步：1、使用宏PHP_FUNCTION定义函数体；2、使用宏ZEND_BEGIN_ARG_INFO和 ZEND_END_ARG_INFO定义参数信息；3、使用宏PHP_FE将函数加入到say_hello_functions中。下面分步说明。
使用宏PHP_FUNCTION定义函数体
1 PHP_FUNCTION(say_hello_func)
2 {
3 char *name;
4 int name_len;
5
6 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &name, &name_len) == FAILURE)
7 {
8 return;
9 }
10 php_printf("Hello %s!", name);
11
12 RETURN_TRUE;
13 }
上文说过，编写PHP扩展时几乎所有东西都不能裸写，而是必须使用相应的宏。从上面代码可以清楚看到这一点。总体来说，核心函数代码一般由如下几部分构成：
定义函数，这一步通过宏PHP_FUNCTION实现，函数的外部名称就是宏后面括号里面的名称。
声明并定义局部变量。
解析参数，这一步通过zend_parse_parameters函数实现，这个函数的作用是从函数用户的输入栈中读取数据，然后转换成相应的函数 参数填入变量以供后面核心功能代码使用。zend_parse_parameters的第一个参数是用户传入参数的个数，可以由宏 “ZEND_NUM_ARGS() TSRMLS_CC”生成；第二个参数是一个字符串，其中每个字母代表一个变量类型，我们只有一个字符串型变量，所以第二个参数是“s”；最后各个参数需 要一些必要的局部变量指针用于存储数据，下表给出了不同变量类型的字母代表及其所需要的局部变量指针。
参数解析完成后就是核心功能代码，我们这里只是输出一行字符，php_printf是Zend版本的printf。
最后的返回值也是通过宏实现的。RETURN_TRUE宏是返回布尔值“true”。
使用宏ZEND_BEGIN_ARG_INFO和ZEND_END_ARG_INFO定义参数信息
参数信息是函数所必要部分，这里不做深究，直接给出相应代码：
1 ZEND_BEGIN_ARG_INFO(arginfo_say_hello_func, 0)
2 ZEND_END_ARG_INFO()
如需了解具体信息请阅读相关宏定义。
使用宏PHP_FE将函数加入到say_hello_functions中
最后，我们需要将刚才定义的函数和参数信息加入到say_hello_functions数组里，代码如下：
1 const zend_function_entry say_hello_functions[] = {
2 PHP_FE(say_hello_func, arginfo_say_hello_func)
3 {NULL, NULL, NULL}
4 };
这一步就是通过PHP_EF宏实现，注意这个数组最后一行必须是{NULL, NULL, NULL} ，请不要删除。
下面是编写完成后的say_hello.c全部代码：
1 /*
2 +----------------------------------------------------------------------+
3 | PHP Version 5 |
4 +----------------------------------------------------------------------+
5 | Copyright (c) 1997-2010 The PHP Group |
6 +----------------------------------------------------------------------+
7 | This source file is subject to version 3.01 of the PHP license, |
8 | that is bundled with this package in the file LICENSE, and is |
9 | available through the world-wide-web at the following url: |
10 | http://www.php.net/license/3_01.txt |
11 | If you did not receive a copy of the PHP license and are unable to |
12 | obtain it through the world-wide-web, please send a note to |
13 | license@php.net so we can mail you a copy immediately. |
14 +----------------------------------------------------------------------+
15 | Author: |
16 +----------------------------------------------------------------------+
17 */
18
19 /* $Id: header 297205 2010-03-30 21:09:07Z johannes $ */
20
21 #ifdef HAVE_CONFIG_H
22 #include "config.h"
23 #endif
24
25 #include "php.h"
26 #include "php_ini.h"
27 #include "ext/standard/info.h"
28 #include "php_say_hello.h"
29
30 /* If you declare any globals in php_say_hello.h uncomment this:
31 ZEND_DECLARE_MODULE_GLOBALS(say_hello)
32 */
33
34 /* True global resources - no need for thread safety here */
35 static int le_say_hello;
36
37 /* {{{ PHP_FUNCTION
38 */
39 PHP_FUNCTION(say_hello_func)
40 {
41 char *name;
42 int name_len;
43
44 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &name, &name_len) == FAILURE)
45 {
46 return;
47 }
48 php_printf("Hello %s!", name);
49
50 RETURN_TRUE;
51 }
52
53 ZEND_BEGIN_ARG_INFO(arginfo_say_hello_func, 0)
54 ZEND_END_ARG_INFO()
55 /* }}} */
56
57 /* {{{ say_hello_functions[]
58 *
59 * Every user visible function must have an entry in say_hello_functions[].
60 */
61 const zend_function_entry say_hello_functions[] = {
62 PHP_FE(say_hello_func, arginfo_say_hello_func)
63 {NULL, NULL, NULL} /* Must be the last line in say_hello_functions[] */
64 };
65 /* }}} */
66
67 /* {{{ say_hello_module_entry
68 */
69 zend_module_entry say_hello_module_entry = {
70 #if ZEND_MODULE_API_NO >= 20010901
71 STANDARD_MODULE_HEADER,
72 #endif
73 "say_hello",
74 say_hello_functions,
75 NULL,
76 NULL,
77 NULL,
78 NULL,
79 PHP_MINFO(say_hello),
80 #if ZEND_MODULE_API_NO >= 20010901
81 "0.1", /* Replace with version number for your extension */
82 #endif
83 STANDARD_MODULE_PROPERTIES
84 };
85 /* }}} */
86
87 #ifdef COMPILE_DL_SAY_HELLO
88 ZEND_GET_MODULE(say_hello)
89 #endif
90
91 /* {{{ PHP_MINFO_FUNCTION
92 */
93 PHP_MINFO_FUNCTION(say_hello)
94 {
95 php_info_print_table_start();
96 php_info_print_table_header(2, "say_hello support", "enabled");
97 php_info_print_table_row(2, "author", "Zhang Yang"); /* Replace with your name */
98 php_info_print_table_end();
99
100 /* Remove comments if you have entries in php.ini
101 DISPLAY_INI_ENTRIES();
102 */
103 }
104 /* }}} */
编译并安装扩展
在say_hello目录下输入下面命令：
/usr/bin/phpize
./configure --with-php-config=/usr/local/php/bin/php-cpnfig
make
make install
这样就完成了say_hello扩展的安装（如果没有报错的话）。
这时如果你去放置php扩展的目录下，会发现多了一个say_hello.so的文件。如下图所示：
下面就是将其加入到php.ini配置中，然后重启Apache（如果需要的话）。这些都是PHP基本配置的内容，我就不详述了。
扩展测试
如果上面顺利完成，这时运行phpinfo()，应该能看到如下信息：
这说明扩展已经安装成功了。然后我们编写一个测试用PHP脚本：
<?php
echo 'use function like this :say_hello_func("Liu Meng!")';
echo '<br>will print:';
say_hello_func('Liu Meng!');
?>
执行这个脚本，结果如下：
posted on 2012-01-11 15:20 kudosharry 阅读(172) 评论(0) 编辑 收藏 举报
