The INI file (php.ini) implementation allows PHP extensions to register and
listen to their own custom INI entries. If these INI entries are assigned a
value either by php.ini, Apache’s .htaccess, or other configuration methods,
the registered INI variable will always be updated with the correct value. This
whole INI framework has many different options and allows for a lot of flexi-
bility. We cover the basics (which gives you a good start) and, with the help of
the other material in this chapter, allows you to do most of what you’ll need for
your day-to-day job.
PHP INI directives are registered with the STD_PHP_INI_ENTRY() macro in
between the PHP_INI_BEGIN()/PHP_INI_END() macros. For example, in myfile.c
you should see something like the following:
PHP_INI_BEGIN()
STD_PHP_INI_ENTRY(”myfile.global_value”, “42″, PHP_INI_ALL,
OnUpdateInt, global_value, zend_myfile_globals, myfile_globals)
STD_PHP_INI_ENTRY(”myfile.global_string”, “foobar”, PHP_INI_ALL,
OnUpdateString, global_string, zend_myfile_globals,
myfile_globals)
PHP_INI_END()
Other macros besides STD_PHP_INI_ENTRY() can be used, but this one is the
most common and should be sufficient for almost all needs (see Table 15.9 for
more information about its parameters):
STD_PHP_INI_ENTRY(name, default_value, modifiable, on_modify,
property_name, struct_type, struct_ptr)
Table 15.9 STD_PHP_INI_ENTRY Macro Parameters
Parameter
Meaning
name
Name of the INI entry.
default_value
The default value, if not specified in the INI file. The default value is
always specified as a string.
modifiable
A bit field specifying under what circumstances the INI entry can be
changed. Possible values are
· PHP_INI_SYSTEM. Values can be changed in system files such as php.ini or
httpd.conf.
· PHP_INI_PERDIR. Values can be changed by .htaccess.
· PHP_INI_USER. Values can be changed by user scripts.
· PHP_INI_ALL. Values can be changed from everywhere.
Table 15.9 STD_PHP_INI_ENTRY Macro Parameters
Parameter
Meaning
on_modify
Callback function that handles the modification for this INI entry. Usu-
ally, you will not write your own handlers and will use some of the pro-
vided ones. These include
· OnUpdateInt
· OnUpdateString
· OnUpdateBool
· OnUpdateStringUnempty
· OnUpdateReal
property_name
Name of the variable that should be updated.
struct_type
Type of the structure the variables resides in. You will usually use the
global variables mechanism, so the type is usually automatically defined
and will be something like zend_myfile_globals.
struct_ptr
The name of the globals structure. By using the global variables mecha-
nism, this would be myfile_globals.
Finally, to make the INI mechanism work correctly with your INI
entries, you need to uncomment the REGISTER_INI_ENTRIES() call in
PHP_MINIT_FUNCTION(myfile) and uncomment the UNREGISTER_INI_ENTRIES()
call in PHP_MSHUTDOWN_FUNCTION(myfile).
Accessing one of the two sample global variables is as simple as writing
MYFILE_G(global_value) and MYFILE_G(global_string) from anywhere in your
extension.
If you’d put the following lines in your php.ini, the value of MYFILE_G
(global_value) would change accordingly to 99:
; php.ini The following line sets the INI entry myfile.global_value
to 99.
myfile.global_value = 99