©
本文档使用 PHP中文网手册 发布
The main source file of a PHP extension contains several new constructs for a C programmer. The most important of these, the one touched first when starting a new extension, is the zend_module structure. This structure contains a wealth of information that tells the Zend Engine about the extension's dependencies, version, callbacks, and other critical data. The structure has mutated considerably over time; this section will focus on the structure as it has appeared since PHP 5.2, and will identify the very few parts which have changed in PHP 5.3.
The zend_module declaration from counter.c looks like this before any code has been written. The example file was generated by ext_skel --extname=counter, with some obsolete constructs removed:
Example #1 zend_module declaration in the counter extension
zend_module_entry counter_module_entry = { STANDARD_MODULE_HEADER, "counter", counter_functions, PHP_MINIT(counter), PHP_MSHUTDOWN(counter), PHP_RINIT(counter), PHP_RSHUTDOWN(counter), PHP_MINFO(counter), "0.1", STANDARD_MODULE_PROPERTIES };
This may look a bit daunting at first glance, but most of it is very simple to understand. Here's the declaration of zend_module from zend_modules.h in PHP 5.3:
Example #2 zend_module definition in PHP 5.3
struct _zend_module_entry { unsigned short size; unsigned int zend_api; unsigned char zend_debug; unsigned char zts; const struct _zend_ini_entry *ini_entry; const struct _zend_module_dep *deps; const char *name; const struct _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); const char *version; size_t globals_size; #ifdef ZTS ts_rsrc_id* globals_id_ptr; #else void* globals_ptr; #endif void (*globals_ctor)(void *global TSRMLS_DC); void (*globals_dtor)(void *global TSRMLS_DC); int (*post_deactivate_func)(void); int module_started; unsigned char type; void *handle; int module_number; };
Many of these fields will never be touched by an extension writer. There are
a number of standard macros that set them to their proper values
automatically. The macro STANDARD_MODULE_HEADER
fills in
everything up to the deps field. Alternatively, the
STANDARD_MODULE_HEADER_EX
will leave the
deps field empty for the developer's use. The developer is
always responsible for everything from name to
version . After that, the
STANDARD_MODULE_PROPERTIES
macro will fill in the rest
of the structure, or the STANDARD_MODULE_PROPERTIES_EX
macro can be used to leave the extension globals and post-deactivation
function fields unfilled. Most modern extensions will make use of module
globals.
Note:
This table gives the values that each field would have if the developer were to fill in the structure entirely by hand, without recourse to any of the shortcut macros. This is not recommended. The "correct" values for many fields may change. Use the macros whenever possible.
Field | Value | Description |
---|---|---|
size [1] [2] [3] | sizeof(zend_module_entry) | The size in bytes of the structure. |
zend_api [1] [2] [3] | ZEND_MODULE_API_NO | The version of the Zend API this module was compiled against. |
zend_debug [1] [2] [3] | ZEND_DEBUG | A flag indicating whether the module was compiled with debugging turned on. |
zts [1] [2] [3] | USING_ZTS | A flag indicating whether the module was compiled with ZTS (TSRM) enabled (see 内存管理). |
ini_entry [1] [3] | NULL | This pointer is used internally by Zend to keep a non-local reference to any INI entries declared for the module. |
deps [3] | NULL | A pointer to a list of dependencies for the module. |
name | "mymodule" | The name of the module. This is the short name, such as "spl" or "standard". |
functions | mymodule_functions | A pointer to the module's function table, which Zend uses to expose functions in the module to user space. |
module_startup_func | PHP_MINIT(mymodule) | A callback function that Zend will call the first time a module is loaded into a particular instance of PHP. |
module_shutdown_func | PHP_MSHUTDOWN(mymodule) | A callback function that Zend will call the when a module is unloaded from a particular instance of PHP, typically during final shutdown. |
request_startup_func | PHP_RINIT(mymodule) | A callback function that Zend will call at the beginning of each request. This should be as short as possible or NULL as calling this has costs on every request. |
request_shutdown_func | PHP_RSHUTDOWN(mymodule) | A callback function that Zend will call at the end of each request. This should be as short as possible or NULL as calling this has costs on every request. |
info_func | PHP_MINFO(mymodule) | A callback function that Zend will call when the phpinfo() function is called. |
version | NO_VERSION_YET | A string giving the version of the module, as specified by the module developer. It is recommended that the version number be either in the format expected by version_compare() (e.g. "1.0.5-dev"), or a CVS or SVN revision number (e.g. "$Rev: 322138 $"). |
globals_size [1] [4] [5] [6] | sizeof(zend_mymodule_globals) | The size of the data structure containing the module's globals, if any. |
globals_id_ptr [1] [4] [5] [6] [7] | &mymodule_globals_id |
Only one of these two fields will exist, depending upon whether the
USING_ZTS constant is TRUE . The former is an index
into TSRM's allocation table for the module's globals, and the latter is
a pointer directly to the globals.
|
globals_ptr [1] [4] [5] [6] [8] | &mymodule_globals | |
globals_ctor [4] [5] [6] | PHP_GINIT(mymodule) | This funtion is called to initialize a module's globals before any module_startup_func . |
globals_dtor [4] [5] [6] | PHP_GSHUTDOWN(mymodule) | This funtion is called to deallocate a module's globals after any module_shutdown_func . |
post_deactivate_func [4] | ZEND_MODULE_POST_ZEND_DEACTIVATE_N(mymodule) | This function is called by Zend after request shutdown. It is rarely used. |
module_started [1] [9] [4] | 0 | These fields are used for Zend's internal tracking information. |
type [1] [9] [4] | 0 | |
handle [1] [9] [4] | NULL | |
module_number [1] [9] [4] | 0 | |
[1]
This field is not intended for use by module developers.
[2]
This field is filled in by STANDARD_MODULE_HEADER_EX .
[3]
This field is filled in by STANDARD_MODULE_HEADER .
[4]
This field is filled in by STANDARD_MODULE_PROPERTIES .
[5]
This field is filled in by NO_MODULE_GLOBALS .
[6]
This field is filled in by PHP_MODULE_GLOBALS .
[7]
This field only exists when USING_ZTS is TRUE .
[8]
This field only exists when USING_ZTS is FALSE .
[9]
This field is filled in by STANDARD_MODULE_PROPERTIES_EX .
|
With all these fields to play with, it can be confusing to know which to use for what purpose. Here is the zend_module definition from the "counter" example extension after updating it to its final form.
Example #3 Counter extension module definition
zend_module_entry counter_module_entry = { STANDARD_MODULE_HEADER, "counter", counter_functions, PHP_MINIT(counter), PHP_MSHUTDOWN(counter), PHP_RINIT(counter), PHP_RSHUTDOWN(counter), PHP_MINFO(counter), NO_VERSION_YET, PHP_MODULE_GLOBALS(counter), PHP_GINIT(counter), PHP_GSHUTDOWN(counter), NULL, STANDARD_MODULE_PROPERTIES_EX };
STANDARD_MODULE_HEADER
is used since this module
doesn't define any dependencies.
NO_VERSION_YET
is a particularly nice way of telling
Zend the module doesn't have a version. It might have been more correct to
place "1.0" here instead in a real module.
PHP_MODULE_GLOBALS
is used
NULL
is used.
STANDARD_MODULE_PROPERTIES_EX
is used to finish the
structure.
Nothing. The only differences in the zend_module structure between PHP 5.2 and PHP 5.3 are a few const keywords.