PHP Manual
Prev	Chapter 31. Source Discussion	Next

Declaration of the Zend Module Block

This block is stored in the structure zend_module_entry and contains all necessary information to describe the contents of this module to Zend. You can see the internal definition of this module in Listing 9.6.

Figure 31-4. Internal declaration of zend_module_entry.

typedef struct _zend_module_entry zend_module_entry;

struct _zend_module_entry {
    unsigned short size;
    unsigned 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;
    int (*global_startup_func)(void);
    int (*global_shutdown_func)(void);

[ Rest of the structure is not interesting here ]

};

Entry	Description
`size`, `zend_api`, `zend_debug` and `zts`	Usually filled with the `"STANDARD_MODULE_HEADER"`, which fills these four members with the size of the whole zend_module_entry, the `ZEND_MODULE_API_NO`, whether it is a debug build or normal build (`ZEND_DEBUG`) and if ZTS is enabled (`USING_ZTS`).
`name`	Contains the module name (for example, `"File functions"`, `"Socket functions"`, `"Crypt"`, etc.). This name will show up in phpinfo(), in the section "Additional Modules."
`functions`	Points to the Zend function block, discussed in the preceding section.
`module_startup_func`	This function is called once upon module initialization and can be used to do one-time initialization steps (such as initial memory allocation, etc.). To indicate a failure during initialization, return `FAILURE`; otherwise, `SUCCESS`. To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_MINIT`.
`module_shutdown_func`	This function is called once upon module shutdown and can be used to do one-time deinitialization steps (such as memory deallocation). This is the counterpart to module_startup_func(). To indicate a failure during deinitialization, return `FAILURE`; otherwise, `SUCCESS`. To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_MSHUTDOWN`.
`request_startup_func`	This function is called once upon every page request and can be used to do one-time initialization steps that are required to process a request. To indicate a failure here, return `FAILURE`; otherwise, `SUCCESS`. Note: As dynamic loadable modules are loaded only on page requests, the request startup function is called right after the module startup function (both initialization events happen at the same time). To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_RINIT`.
`request_shutdown_func`	This function is called once after every page request and works as counterpart to request_startup_func(). To indicate a failure here, return `FAILURE`; otherwise, `SUCCESS`. Note: As dynamic loadable modules are loaded only on page requests, the request shutdown function is immediately followed by a call to the module shutdown handler (both deinitialization events happen at the same time). To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_RSHUTDOWN`.
`info_func`	When phpinfo() is called in a script, Zend cycles through all loaded modules and calls this function. Every module then has the chance to print its own "footprint" into the output page. Generally this is used to dump environmental or statistical information. To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_MINFO`.
`version`	The version of the module. You can use `NO_VERSION_YET` if you don't want to give the module a version number yet, but we really recommend that you add a version string here. Such a version string can look like this (in chronological order): `"2.5-dev"`, `"2.5RC1"`, `"2.5"` or `"2.5pl3"`.
`global_startup_func`	The global startup functions are rarely used. You should usually skip through the rest of this structure by placing the macro `STANDARD_MODULE_PROPERTIES`. To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_GINIT`.
`global_shutdown_func`	To mark this field as unused, use `NULL`. To declare a function, use the macro `ZEND_GSHUTDOWN`.
Remaining structure elements	These are used internally and can be prefilled by using the macro `STANDARD_MODULE_PROPERTIES_EX`. You should not assign any values to them. Use `STANDARD_MODULE_PROPERTIES_EX` only if you use global startup and shutdown functions; otherwise, use `STANDARD_MODULE_PROPERTIES` directly.

In our example, this structure is implemented as follows:
zend_module_entry firstmod_module_entry = { STANDARD_MODULE_HEADER, "First Module", firstmod_functions, NULL, NULL, NULL, NULL, NULL, NO_VERSION_YET, STANDARD_MODULE_PROPERTIES, };
This is basically the easiest and most minimal set of values you could ever use. The module name is set to First Module, then the function list is referenced, after which all startup and shutdown functions are marked as being unused.

For reference purposes, you can find a list of the macros involved in declared startup and shutdown functions in Table 9.3. These are not used in our basic example yet, but will be demonstrated later on. You should make use of these macros to declare your startup and shutdown functions, as these require special arguments to be passed (INIT_FUNC_ARGS and SHUTDOWN_FUNC_ARGS), which are automatically included into the function declaration when using the predefined macros. If you declare your functions manually and the PHP developers decide that a change in the argument list is necessary, you'll have to change your module sources to remain compatible.

Figure 31-5. Macros to Declare Startup and Shutdown Functions

Macro	Description
`ZEND_MINIT(module)`	Declares a function for module startup. The generated name will be `zend_minit_<module>` (for example, `zend_minit_first_module`). Use in conjunction with `ZEND_MINIT_FUNCTION`.
`ZEND_MSHUTDOWN(module)`	Declares a function for module shutdown. The generated name will be `zend_mshutdown_<module>` (for example, `zend_mshutdown_first_module`). Use in conjunction with `ZEND_MSHUTDOWN_FUNCTION`.
`ZEND_RINIT(module)`	Declares a function for request startup. The generated name will be `zend_rinit_<module>` (for example, `zend_rinit_first_module`). Use in conjunction with `ZEND_RINIT_FUNCTION`.
`ZEND_RSHUTDOWN(module)`	Declares a function for request shutdown. The generated name will be `zend_rshutdown_<module>` (for example, `zend_rshutdown_first_module`). Use in conjunction with `ZEND_RSHUTDOWN_FUNCTION`.
`ZEND_GINIT(module)`	Declares a function for global startup. The generated name will be `zend_ginit_<module>` (for example, `zend_ginit_first_module`). Use in conjunction with `ZEND_GINIT_FUNCTION`.
`ZEND_GSHUTDOWN(module)`	Declares a function for global shutdown. The generated name will be `zend_gshutdown_<module>` (for example, `zend_gshutdown_first_module`). Use in conjunction with `ZEND_GSHUTDOWN_FUNCTION`.
`ZEND_MINFO(module)`	Declares a function for printing module information, used when phpinfo() is called. The generated name will be `zend_info_<module>` (for example, `zend_info_first_module`). Use in conjunction with `ZEND_MINFO_FUNCTION`.

Prev	Home	Next
Declaration of the Zend Function Block	Up	Creation of get_module()