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 59-1.
Table 59-1. Macros to Access Initialization Entries in PHP
| Macro | Syntax |
| 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();
} |