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. Listing 9.6. Internal declaration of `zend_module_entry`.

    typedef struct _zend_module_entry zend_module_entry;

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

    [ Rest of the structure is not interesting here ]

    };

Entry | Description
`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`.
`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. Table 9.3. 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()()