<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML ><HEAD ><TITLE >Initialization File Support</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="Manual PHP" HREF="index.html"><LINK REL="UP" TITLE="Zend API" HREF="zend.html"><LINK REL="PREVIOUS" TITLE="Calling User Functions" HREF="zend.calling-user-functions.html"><LINK REL="NEXT" TITLE="Where to Go from Here" HREF="zend.where-to-go.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=ISO-8859-2"></HEAD ><BODY CLASS="chapter" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Manual PHP</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="zend.calling-user-functions.html" ACCESSKEY="P" >Înapoi</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="zend.where-to-go.html" ACCESSKEY="N" >Înainte</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="chapter" ><H1 ><A NAME="zend.ini-file-support" >Cap. 41. Initialization File Support</A ></H1 ><P > 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. </P ><P > To create an .ini section in your own module, use the macros <VAR CLASS="literal" >PHP_INI_BEGIN()</VAR > to mark the beginning of such a section and <VAR CLASS="literal" >PHP_INI_END()</VAR > to mark its end. In between you can use <VAR CLASS="literal" >PHP_INI_ENTRY()</VAR > to create entries. <TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="programlisting" >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()</PRE ></TD ></TR ></TABLE > The <VAR CLASS="literal" >PHP_INI_ENTRY()</VAR > 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. </P ><P > The permissions are grouped into three sections:<VAR CLASS="literal" >PHP_INI_SYSTEM</VAR > allows a change only directly in the <TT CLASS="filename" >php.ini</TT > file; <VAR CLASS="literal" >PHP_INI_USER</VAR > allows a change to be overridden by a user at runtime using additional configuration files, such as <TT CLASS="filename" >.htaccess</TT >; and <VAR CLASS="literal" >PHP_INI_ALL</VAR > allows changes to be made without restrictions. There's also a fourth level, <VAR CLASS="literal" >PHP_INI_PERDIR</VAR >, for which we couldn't verify its behavior yet. </P ><P > 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 <VAR CLASS="literal" >PHP_INI_MH</VAR > macro: <TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="programlisting" >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); }</PRE ></TD ></TR ></TABLE > The new value is given to the change handler as string in the variable <VAR CLASS="envar" >new_value</VAR >. When looking at the definition of <VAR CLASS="literal" >PHP_INI_MH</VAR >, you actually have a few parameters to use: <TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="programlisting" >#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)</PRE ></TD ></TR ></TABLE > All these definitions can be found in <TT CLASS="filename" >php_ini.h</TT >. 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 <VAR CLASS="literal" >PHP_INI_ENTRY1</VAR > (allowing one additional argument), <VAR CLASS="literal" >PHP_INI_ENTRY2</VAR > (allowing two additional arguments), and <VAR CLASS="literal" >PHP_INI_ENTRY3</VAR > (allowing three additional arguments). </P ><P > 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. </P ><P > Access to initialization entries can also be handled with the macros shown in <A HREF="zend.ini-file-support.html#table.ini-macros" >Tabel 41-1</A >. </P ><DIV CLASS="table" ><A NAME="table.ini-macros" ></A ><P ><B >Tabel 41-1. Macros to Access Initialization Entries in PHP</B ></P ><TABLE BORDER="1" CLASS="CALSTABLE" ><COL WIDTH="1*" TITLE="col1"><COL WIDTH="1.66*" TITLE="col2"><TBODY ><TR ><TD >Macro</TD ><TD >Description</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_INT(name)</VAR ></TD ><TD >Returns the current value of entry <VAR CLASS="literal" >name</VAR > as integer (long).</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_FLT(name)</VAR ></TD ><TD >Returns the current value of entry <VAR CLASS="literal" >name</VAR > as float (double).</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_STR(name)</VAR ></TD ><TD >Returns the current value of entry <VAR CLASS="literal" >name</VAR > as string. <SPAN CLASS="emphasis" ><I CLASS="emphasis" >Note:</I ></SPAN > This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory.</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_BOOL(name)</VAR ></TD ><TD >Returns the current value of entry <VAR CLASS="literal" >name</VAR > as Boolean (defined as <VAR CLASS="envar" >zend_bool</VAR >, which currently means <VAR CLASS="envar" >unsigned char</VAR >).</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_ORIG_INT(name)</VAR ></TD ><TD >Returns the original value of entry <VAR CLASS="literal" >name</VAR > as integer (long).</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_ORIG_FLT(name)</VAR ></TD ><TD >Returns the original value of entry <VAR CLASS="literal" >name</VAR > as float (double).</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_ORIG_STR(name)</VAR ></TD ><TD >Returns the original value of entry <VAR CLASS="literal" >name</VAR > as string. Note: This string is not duplicated, but instead points to internal data. Further access requires duplication to local memory.</TD ></TR ><TR ><TD ><VAR CLASS="literal" >INI_ORIG_BOOL(name)</VAR ></TD ><TD >Returns the original value of entry <VAR CLASS="literal" >name</VAR > as Boolean (defined as <VAR CLASS="envar" >zend_bool</VAR >, which currently means <VAR CLASS="envar" >unsigned char</VAR >).</TD ></TR ></TBODY ></TABLE ></DIV ><P > Finally, you have to introduce your initialization entries to PHP. This can be done in the module startup and shutdown functions, using the macros <VAR CLASS="literal" >REGISTER_INI_ENTRIES()</VAR > and <VAR CLASS="literal" >UNREGISTER_INI_ENTRIES()</VAR >: <TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="programlisting" >ZEND_MINIT_FUNCTION(mymodule) { REGISTER_INI_ENTRIES(); } ZEND_MSHUTDOWN_FUNCTION(mymodule) { UNREGISTER_INI_ENTRIES(); }</PRE ></TD ></TR ></TABLE > </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="zend.calling-user-functions.html" ACCESSKEY="P" >Înapoi</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Acasã</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="zend.where-to-go.html" ACCESSKEY="N" >Înainte</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Calling User Functions</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="zend.html" ACCESSKEY="U" >Sus</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Where to Go from Here</TD ></TR ></TABLE ></DIV ></BODY ></HTML >