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 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); } |
#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) |
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
表39-1
.
表 39-1Macros 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(); } |