Capítulo 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 Tabla 39_1_

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(); }