CHAPTER 15 – Adding Custom INI Directives

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