PHP扩展代码结构详解

PHP扩展代码结构详解 ：

这个是继：使用ext_skel和phpize构建php5扩展 内容 （拆分出来） Zend_API：深入_PHP_内核：http://cn2.php.net/manual/zh/internals2.ze1.php

我们使用ext_skel创建扩展 hello_module,该模块包含一个方法：hello_world。

使用ext_skel 生成的代码都是PHP_开头的宏, 而不是ZEND_开头. 实际上这两者是一样的。

在源代码src/main/PHP.h 中发现： PHP_FUNCTION 就是ZEND_FUNCTION的别名，即：

1. #define PHP_FUNCTION ZEND_FUNCTION /* <acronym title="Hypertext Preprocessor">PHP</acronym>-named Zend macro wrappers */

其实，很多”PHP_”开头的宏都用对应的”ZEND_”开头的宏，这个应该是为兼容之前的版本吧。

php_hello_module.h

1. /* $Id: header 252479 2008-02-07 19:39:50Z iliaa $ */
2. #ifndef PHP_HELLO_MODULE_H
3. #define PHP_HELLO_MODULE_H
4. extern zend_module_entry hello_module_module_entry;
5. #define phpext_hello_module_ptr &hello_module_module_entry
6. #ifdef PHP_WIN32
7. # define PHP_HELLO_MODULE_API __declspec(dllexport)
8. #elif defined(__GNUC__) && __GNUC__ >= 4
9. # define PHP_HELLO_MODULE_API __attribute__ ((visibility("default")))
10. #else
11. # define PHP_HELLO_MODULE_API
12. #endif
13. #ifdef ZTS
14. #include "TSRM.h"
15. #endif
16. PHP_MINIT_FUNCTION(hello_module); //声明加载模块时调用的函数
17. PHP_MSHUTDOWN_FUNCTION(hello_module);//声明卸载模块时调用的函数
18. PHP_RINIT_FUNCTION(hello_module); //声明请求时调用的函数
19. PHP_RSHUTDOWN_FUNCTION(hello_module);//声明请求结束时调用的函数
20. PHP_MINFO_FUNCTION(hello_module); //声明模块信息函数,即可以在phpinfo看到的信息
21. PHP_FUNCTION(confirm_hello_module_compiled); /* For testing, remove later. */
22. /*********** 2）声明导出函数 ************************************************/
23. PHP_FUNCTION(hello_world);
24. /*
25. Declare any global variables you may need between the BEGIN
26. and END macros here:
27. ZEND_BEGIN_MODULE_GLOBALS(hello_module)
28. long global_value;
29. char *global_string;
30. ZEND_END_MODULE_GLOBALS(hello_module)
31. */
32. /* In every utility function you add that needs to use variables
33. in php_hello_module_globals, call TSRMLS_FETCH(); after declaring other
34. variables used by that function, or better yet, pass in TSRMLS_CC
35. after the last function argument and declare your utility function
36. with TSRMLS_DC after the last declared argument. Always refer to
37. the globals in your function as HELLO_MODULE_G(variable). You are
38. encouraged to rename these macros something shorter, see
39. examples in any other php module directory.
40. */
41. #ifdef ZTS
42. #define HELLO_MODULE_G(v) TSRMG(hello_module_globals_id, zend_hello_module_globals *, v)
43. #else
44. #define HELLO_MODULE_G(v) (hello_module_globals.v)
45. #endif
46. #endif /* PHP_HELLO_MODULE_H */

hello_module.c

1. /* $Id: header 252479 2008-02-07 19:39:50Z iliaa $ */
2. #ifdef HAVE_CONFIG_H
3. #include "config.h"
4. #endif
5. /***********************1）包含头文件(引入所需要的宏、API定义等) **************************/
6. #include "php.h" //1）包含头文件(引入所需要的宏、API定义等)；#include "php_ini.h"#include "ext/standard/info.h"#include "php_hello_module.h"/* If you declare any globals in php_hello_module.h uncomment this:ZEND_DECLARE_MODULE_GLOBALS(hello_module)*//* True global resources - no need for thread safety here */static int le_hello_module;
7. /************ 3)声明（引入）Zend（PHP）函数块 ******************/
8. /* {{{ hello_module_functions[] * * Every user visible function must have an entry in hello_module_functions[]. */
9. const zend_function_entry hello_module_functions[] = {
10. PHP_FE(hello_world, NULL)
11. PHP_FE(confirm_hello_module_compiled, NULL) /* For testing, remove later. */
12. {NULL, NULL, NULL} /* Must be the last line in hello_module_functions[] */
13. };
14. /* }}} */
15. /*********************************4)声明 Zend模块 ***********************/
16. /* {{{ hello_module_module_entry
17. */
18. zend_module_entry hello_module_module_entry = {
19. #if ZEND_MODULE_API_NO >= 20010901
20. STANDARD_MODULE_HEADER,
21. #endif
22. "hello_module",
23. hello_module_functions, /* 4 )声明 Zend模块 */
24. PHP_MINIT(hello_module),
25. PHP_MSHUTDOWN(hello_module),
26. PHP_RINIT(hello_module), /* Replace with NULL if there's nothing to do at request start */
27. PHP_RSHUTDOWN(hello_module), /* Replace with NULL if there's nothing to do at request end */
28. PHP_MINFO(hello_module),
29. #if ZEND_MODULE_API_NO >= 20010901
30. "0.1", /* Replace with version number for your extension */
31. #endif
32. STANDARD_MODULE_PROPERTIES
33. };
34. /* }}} */
35. /****************** 5) 实现get_module()函数 ***********************/
36. #ifdef COMPILE_DL_HELLO_MODULE
37. ZEND_GET_MODULE(hello_module)
38. #endif
39. /* {{{ PHP_INI
40. */
41. /* Remove comments and fill if you need to have entries in php.ini
42. PHP_INI_BEGIN()
43. STD_PHP_INI_ENTRY("hello_module.global_value", "42", PHP_INI_ALL, OnUpdateLong, global_value, zend_hello_module_globals, hello_module_globals)
44. STD_PHP_INI_ENTRY("hello_module.global_string", "foobar", PHP_INI_ALL, OnUpdateString, global_string, zend_hello_module_globals, hello_module_globals)
45. PHP_INI_END()
46. */
47. /* }}} */
48. /* {{{ php_hello_module_init_globals
49. */
50. /* Uncomment this function if you have INI entries
51. static void php_hello_module_init_globals(zend_hello_module_globals *hello_module_globals)
52. {
53. hello_module_globals->global_value = 0;
54. hello_module_globals->global_string = NULL;
55. }
56. */
57. /* }}} */
58. /* {{{ PHP_MINIT_FUNCTION
59. */
60. PHP_MINIT_FUNCTION(hello_module)
61. {
62. /* If you have INI entries, uncomment these lines
63. REGISTER_INI_ENTRIES();
64. */
65. return SUCCESS;
66. }
67. /* }}} */
68. /* {{{ PHP_MSHUTDOWN_FUNCTION
69. */
70. PHP_MSHUTDOWN_FUNCTION(hello_module)
71. {
72. /* uncomment this line if you have INI entries
73. UNREGISTER_INI_ENTRIES();
74. */
75. return SUCCESS;
76. }
77. /* }}} */
78. /* Remove if there's nothing to do at request start */
79. /* {{{ PHP_RINIT_FUNCTION
80. */
81. PHP_RINIT_FUNCTION(hello_module)
82. {
83. return SUCCESS;
84. }
85. /* }}} */
86. /* Remove if there's nothing to do at request end */
87. /* {{{ PHP_RSHUTDOWN_FUNCTION
88. */
89. PHP_RSHUTDOWN_FUNCTION(hello_module)
90. {
91. return SUCCESS;
92. }
93. /* }}} */
94. /* {{{ PHP_MINFO_FUNCTION
95. */
96. PHP_MINFO_FUNCTION(hello_module)
97. {
98. php_info_print_table_start();
99. php_info_print_table_header(2, "hello_module support", "enabled");
100. php_info_print_table_end();
101. /* Remove comments if you have entries in php.ini
102. DISPLAY_INI_ENTRIES();
103. */
104. }
105. /* }}} */
106. /* Remove the following function when you have succesfully modified config.m4
107. so that your module can be compiled into PHP, it exists only for testing
108. purposes. */
109. /* Every user-visible function in PHP should document itself in the source */
110. /* {{{ proto string confirm_hello_module_compiled(string arg)
111. Return a string to confirm that the module is compiled in */
112. PHP_FUNCTION(confirm_hello_module_compiled)
113. {
114. char *arg = NULL;
115. int arg_len, len;
116. char *strg;
117. if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &arg, &arg_len) == FAILURE) {
118. return;
119. }
120. len = spprintf(&strg, 0, "Congratulations! You have successfully modified ext/%.78s/config.m4. Module %.78s is now compiled into PHP.", "hello_module", arg);
121. RETURN_STRINGL(strg, len, 0);
122. }
123. /* }}} */
124. /* The previous line is meant for vim and emacs, so it can correctly fold and
125. unfold functions in source code. See the corresponding marks just before
126. function definition, where the functions purpose is also documented. Please
127. follow this convention for the convenience of others editing your code.
128. */
129. /**************************** 6)实现导出函数 *******************************************/
130. PHP_FUNCTION(hello_world)
131. {
132. RETURN_STRING("HelloWorld", 1);
133. }

模块结构

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

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

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

· 声明 Zend函数块；

· 声明 Zend模块；

· 实现get_module()函数；

· 实现导出函数。

1) 包含头文件

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

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

2)声明导出函数

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

1. ZEND_FUNCTION( hello_world );

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

1. void zif_hello_world ( INTERNAL_FUNCTION_PARAMETERS );

接着再把 INTERNAL_FUNCTION_PARAMETERS展开就会得到这样一个结果, 即ZEND_FUNCTION最终扩展结果：

1. void zif_my_function( int ht
2. , zval *return_value
3. , zval *this_ptr
4. , intreturn_value_used
5. ,zend_executor_globals * executor_globals
6. );

可见，ZEND_FUNCTION就是简单的声明了一个名为zif_ first_module的C函数，zif可能是”Zend Internal Function”的缩写。

在解释器（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根本就是 zval的一个别名）。但由于INTERNAL_FUNCTION_PARAMETERS是一个 Zend宏，因此我们在上面的声明中使用了zval。在编写代码时，你也应该总是使用 zval以遵循新的 Zend API规范。

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

PHP调用函数的 Zend参数:

3）声明（引入）Zend（PHP）函数块

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

1. typedef struct _zend_function_entry {
2. char *fname;
3. void (*handler)(INTERNAL_FUNCTION_PARAMETERS);
4. unsigned char *func_arg_types;
5. } zend_function_entry;

对于我们要创建的模块：hello_module.该模块提供一个方法：hello_word，可以这样声明：

1. const zend_function_entry hello_module_functions[] = {
2. PHP_FE(hello_world, NULL)
3. PHP_FE(confirm_hello_module_compiled, NULL) /* For testing, remove later. */
4. {NULL, NULL, NULL} /* Must be the last line in hello_module_functions[] */
5. };

这样完成C函数到PHP函数的映射的语句。

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

注意:

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

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

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

用来定义函数的宏

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

4）声明 Zend模块

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

1. typedef struct _zend_module_entry zend_module_entry;
2. struct _zend_module_entry {
3. unsigned short size;
4. unsigned int zend_api;
5. unsigned char zend_debug;
6. unsigned char zts;
7. char *name;
8. zend_function_entry *functions;
9. int (*module_startup_func)(INIT_FUNC_ARGS);
10. int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
11. int (*request_startup_func)(INIT_FUNC_ARGS);
12. int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
13. void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
14. char *version;
15. … // 其余的一些我们不感兴趣的信息
16. };

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

1. zend_module_entry hello_module_module_entry = {
2. #if ZEND_MODULE_API_NO >= 20010901
3. STANDARD_MODULE_HEADER,
4. #endif
5. "hello_module",
6. hello_module_functions,
7. PHP_MINIT(hello_module),
8. PHP_MSHUTDOWN(hello_module),
9. PHP_RINIT(hello_module), /* Replace with NULL if there's nothing to do at request start */
10. PHP_RSHUTDOWN(hello_module), /* Replace with NULL if there's nothing to do at request end */
11. PHP_MINFO(hello_module),
12. #if ZEND_MODULE_API_NO >= 20010901
13. "0.1", /* Replace with version number for your extension */
14. #endif
15. STANDARD_MODULE_PROPERTIES
16. };

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

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

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

5) 实现 get_module()函数

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

1. #ifdef COMPILE_DL_HELLO_MODULE
2. ZEND_GET_MODULE(hello_module)
3. #endif

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

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

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

6)实现导出函数

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

1. PHP_FUNCTION(hello_world)
2. {
3. RETURN_STRING("HelloWorld", 1);
4. }

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

7）启动和终止函数

Zend允许模块在加载和卸载时收到通知，以进行初始化和清除工作，我们要做的就是把相应函数传递给Zend，它会在合适的时机自动调用。

Zend提供了如下四个宏，分别用于声明对应的函数：

在声明模块信息里面

1. zend_module_entry hello_module_module_entry = {
2. #if ZEND_MODULE_API_NO >= 20010901
3. STANDARD_MODULE_HEADER,
4. #endif
5. "hello_module",
6. hello_module_functions,
7. PHP_MINIT(hello_module),
8. PHP_MSHUTDOWN(hello_module),
9. PHP_RINIT(hello_module), /* Replace with NULL if there's nothing to do at request start */
10. PHP_RSHUTDOWN(hello_module), /* Replace with NULL if there's nothing to do at request end */
11. PHP_MINFO(hello_module),
12. #if ZEND_MODULE_API_NO >= 20010901
13. "0.1", /* Replace with version number for your extension */
14. #endif
15. STANDARD_MODULE_PROPERTIES
16. };

1）STANDARD_MODULE_HEADER和STANDARD_MODULE_PROPERTIES宏填充了该结构的首尾部分，具体填充了什么并不是我们需要关心的，并且为了兼容后续版本也最好不要手工修改。

2）第二、三项是模块名称和导出函数，名称可以任意填写，导出函数就是我们在前面准备好的zend_function_entry数组。

3）后面的四个参数内容：

1. PHP_MINIT(hello_module),
2. PHP_MSHUTDOWN(hello_module),
3. PHP_RINIT(hello_module), /* Replace with NULL if there's nothing to do at request start */
4. PHP_RSHUTDOWN(hello_module), /* Replace with NULL if there's nothing to do at request end */

就是用于启动和终止函数，他们都是指针函数。

4) 参数值 PHP_MINFO(hello_module),也是指针函数，用于配合phpinfo()来显示模块信息。

这些宏的用法和ZEND_FUNCTION宏一样，展开后就是声明了特定原型的函数，其参数module可以是任意的，但最好使用模块名称。这些函数的参数中，对我们有用的是int module_number，它是模块号，全局唯一，后面会提到其用处。

在声明和实现相应函数时，都应该使用这些宏。最后，需要把这些函数填写到zend_module_entry里，可按顺序使用如下的宏，这些宏生成相应的函数名称：

在我们的hello_module中，对应的声明（由于ext_skel生成的代码是PHP API ，和ZEND API本质上一样）

1. PHP_MINIT_FUNCTION(hello_module);
2. PHP_MSHUTDOWN_FUNCTION(hello_module);
3. PHP_RINIT_FUNCTION(hello_module);
4. PHP_RSHUTDOWN_FUNCTION(hello_module);
5. PHP_MINFO_FUNCTION(hello_module);

对应的实现：

1. /* {{{ PHP_MINIT_FUNCTION
2. */
3. PHP_MINIT_FUNCTION(hello_module)
4. {
5. /* If you have INI entries, uncomment these lines
6. REGISTER_INI_ENTRIES();
7. */
8. return SUCCESS;
9. }
10. /* }}} */
11. /* {{{ PHP_MSHUTDOWN_FUNCTION
12. */
13. PHP_MSHUTDOWN_FUNCTION(hello_module)
14. {
15. /* uncomment this line if you have INI entries
16. UNREGISTER_INI_ENTRIES();
17. */
18. return SUCCESS;
19. }
20. /* }}} */
21. /* Remove if there's nothing to do at request start */
22. /* {{{ PHP_RINIT_FUNCTION
23. */
24. PHP_RINIT_FUNCTION(hello_module)
25. {
26. return SUCCESS;
27. }
28. /* }}} */
29. /* Remove if there's nothing to do at request end */
30. /* {{{ PHP_RSHUTDOWN_FUNCTION
31. */
32. PHP_RSHUTDOWN_FUNCTION(hello_module)
33. {
34. return SUCCESS;
35. }
36. /* }}} */
37. /* {{{ PHP_MINFO_FUNCTION
38. */
39. PHP_MINFO_FUNCTION(hello_module)
40. {
41. php_info_print_table_start();
42. php_info_print_table_header(2, "hello_module support", "enabled");
43. php_info_print_table_end();
44. /* Remove comments if you have entries in php.ini
45. DISPLAY_INI_ENTRIES();
46. */
47. }
48. /* }}} */

如果不想使用这个函数，对应的参数都可以设置为null

那么模块声明

1. zend_module_entry hello_module_module_entry = {
2. #if ZEND_MODULE_API_NO >= 20010901
3. STANDARD_MODULE_HEADER,
4. #endif
5. "hello_module",
6. hello_module_functions,
7. NULL,
8. NULL,
9. NULL, /* Replace with NULL if there's nothing to do at request start */
10. NULL, /* Replace with NULL if there's nothing to do at request end */
11. NULL,
12. #if ZEND_MODULE_API_NO >= 20010901
13. "0.1", /* Replace with version number for your extension */
14. #endif
15. STANDARD_MODULE_PROPERTIES
16. };