Initialization File Support

PHP Manual
Prev |  | Next

# Chapter 39. Initialization File Support

PHP 4 features a redesigned initialization file support. It's now possible to specify default initialization entries directly in your code, read and change these values at runtime, and create message handlers for change notifications.

To create an .ini section in your own module, use the macros `PHP_INI_BEGIN()` to mark the beginning of such a section and `PHP_INI_END()` to mark its end. In between you can use `PHP_INI_ENTRY()` to create entries.

    PHP_INI_BEGIN()
    PHP_INI_ENTRY("first_ini_entry",  "has_string_value", PHP_INI_ALL, NULL)
    PHP_INI_ENTRY("second_ini_entry", "2",                PHP_INI_SYSTEM, OnChangeSecond)
    PHP_INI_ENTRY("third_ini_entry",  "xyz",              PHP_INI_USER, NULL)
    PHP_INI_END()

The `PHP_INI_ENTRY()` macro accepts four parameters: the entry name, the entry value, its change permissions, and a pointer to a change-notification handler. Both entry name and value must be specified as strings, regardless of whether they really are strings or integers.

The permissions are grouped into three sections:`PHP_INI_SYSTEM` allows a change only directly in the `php.ini` file; `PHP_INI_USER` allows a change to be overridden by a user at runtime using additional configuration files, such as `.htaccess`; and `PHP_INI_ALL` allows changes to be made without restrictions. There's also a fourth level, `PHP_INI_PERDIR`, for which we couldn't verify its behavior yet.

The fourth parameter consists of a pointer to a change-notification handler. Whenever one of these initialization entries is changed, this handler is called. Such a handler can be declared using the `PHP_INI_MH` macro:

    PHP_INI_MH(OnChangeSecond);             // handler for ini-entry "second_ini_entry"

    // specify ini-entries here

    PHP_INI_MH(OnChangeSecond)
    {

        zend_printf("Message caught, our ini entry has been changed to %s<br>", new_value);

        return(SUCCESS);

    }

The new value is given to the change handler as string in the variable `new_value`. When looking at the definition of `PHP_INI_MH`, you actually have a few parameters to use:

    #define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value,
                                      uint new_value_length, void *mh_arg1,
                                      void *mh_arg2, void *mh_arg3)

All these definitions can be found in `php_ini.h`. Your message handler will have access to a structure that contains the full entry, the new value, its length, and three optional arguments. These optional arguments can be specified with the additional macros `PHP_INI_ENTRY1` (allowing one additional argument), `PHP_INI_ENTRY2` (allowing two additional arguments), and `PHP_INI_ENTRY3` (allowing three additional arguments).

The change-notification handlers should be used to cache initialization entries locally for faster access or to perform certain tasks that are required if a value changes. For example, if a constant connection to a certain host is required by a module and someone changes the hostname, automatically terminate the old connection and attempt a new one.

Access to initialization entries can also be handled with the macros shown in Table 39-1.

Table 39-1. Macros to Access Initialization Entries in PHP

Macro | Description
`INI_INT(name)` | Returns the current value of entry `name` as integer (long).
`INI_FLT(name)` | Returns the current value of entry `name` as float (double).
`INI_STR(name)` | Returns the current value of entry `name` as string. Note: This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory.
`INI_BOOL(name)` | Returns the current value of entry `name` as Boolean (defined as `zend_bool`, which currently means `unsigned char`).
`INI_ORIG_INT(name)` | Returns the original value of entry `name` as integer (long).
`INI_ORIG_FLT(name)` | Returns the original value of entry `name` as float (double).
`INI_ORIG_STR(name)` | Returns the original value of entry `name` as string. Note: This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory.
`INI_ORIG_BOOL(name)` | Returns the original value of entry `name` as Boolean (defined as `zend_bool`, which currently means `unsigned char`).

Finally, you have to introduce your initialization entries to PHP. This can be done in the module startup and shutdown functions, using the macros `REGISTER_INI_ENTRIES()` and `UNREGISTER_INI_ENTRIES()`:

    ZEND_MINIT_FUNCTION(mymodule)
    {

        REGISTER_INI_ENTRIES();

    }

    ZEND_MSHUTDOWN_FUNCTION(mymodule)
    {

        UNREGISTER_INI_ENTRIES();

    }

Prev | Home | Next
Calling User Functions | Up | Where to Go from Here