php-doc-en/internals/zendapi/ini-file-support.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
 <!-- $Id: ini-file-support.xml,v 1.1 2005-08-21 16:27:06 goba Exp $ -->
 <sect1 id="zend.ini-file-support"> 
  <title>Initialization File Support</title> 
  <para>
   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.
  </para> 
  <para>
   To create an .ini section in your own module, use the
   macros <literal>PHP_INI_BEGIN()</literal> to mark the beginning of such a
   section and <literal>PHP_INI_END()</literal> to mark its end. In between you can
   use <literal>PHP_INI_ENTRY()</literal> to create entries.
<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()
</programlisting>
   The <literal>PHP_INI_ENTRY()</literal> 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.
  </para> 
  <para>
   The permissions are grouped into three
   sections:<literal>PHP_INI_SYSTEM</literal> allows a change only directly in
   the <filename>php.ini</filename> file; <literal>PHP_INI_USER</literal> allows
   a change to be overridden by a user at runtime using additional
   configuration files, such as <filename>.htaccess</filename>; and <literal>PHP_INI_ALL</literal> allows
   changes to be made without restrictions. There's also a fourth level,
   <literal>PHP_INI_PERDIR</literal>, for which we couldn't verify its behavior
   yet.
  </para> 
  <para>
   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
   <literal>PHP_INI_MH</literal> macro: 
   <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&lt;br&gt;", new_value);

    return(SUCCESS);

}
   </programlisting>
   The new value is given to the change handler as string in
   the variable <envar>new_value</envar>. When looking at the definition
   of <literal>PHP_INI_MH</literal>, you actually have a few parameters to use: 
   <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)
   </programlisting>
   All these definitions can be found
   in <filename>php_ini.h</filename>. 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 <literal>PHP_INI_ENTRY1</literal> (allowing one additional
   argument), <literal>PHP_INI_ENTRY2</literal> (allowing two additional arguments),
   and <literal>PHP_INI_ENTRY3</literal> (allowing three additional
   arguments).
  </para> 
  <para>
   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.
  </para> 
  <para>
   Access to initialization entries can also be handled with the macros 
   shown in <xref linkend='table.ini-macros'/>.
  </para> 
  <table id='table.ini-macros'> 
   <title>Macros to Access Initialization Entries in PHP</title> 
    <tgroup cols="2">
     <colspec colnum="1" colname="col1" colwidth="1.00*"/>
     <colspec colnum="2" colname="col2" colwidth="1.66*"/> 
     <tbody> 
      <row> 
       <entry colname="col1">Macro</entry> 
       <entry colname="col2">Description</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_INT(name)</literal></entry> 
       <entry colname="col2">Returns the current value of
        entry <literal>name</literal> as integer (long).</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_FLT(name)</literal></entry> 
       <entry colname="col2">Returns the current value of
        entry <literal>name</literal> as float (double).</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_STR(name)</literal></entry> 
       <entry colname="col2">Returns the current value of
        entry <literal>name</literal> as string. <emphasis>Note:</emphasis> This string is not duplicated, but
        instead points to internal data. Further access requires duplication to local
        memory.</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_BOOL(name)</literal></entry> 
       <entry colname="col2">Returns the current value of
        entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>,
        which currently means <envar>unsigned char</envar>).</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_ORIG_INT(name)</literal></entry> 
       <entry colname="col2">Returns the original value of
        entry <literal>name</literal> as integer (long).</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_ORIG_FLT(name)</literal></entry> 
       <entry colname="col2">Returns the original value of
        entry <literal>name</literal> as float (double).</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_ORIG_STR(name)</literal></entry> 
       <entry colname="col2">Returns the original value of
        entry <literal>name</literal> as string. Note: This string is not duplicated, but
        instead points to internal data. Further access requires duplication to local
        memory.</entry> 
      </row> 
      <row> 
       <entry colname="col1"><literal>INI_ORIG_BOOL(name)</literal></entry> 
       <entry colname="col2">Returns the original value of
        entry <literal>name</literal> as Boolean (defined as <envar>zend_bool</envar>, which
        currently means <envar>unsigned char</envar>).</entry> 
      </row> 
     </tbody> 
    </tgroup> 
  </table> 
  <para>
   Finally, you have to introduce your initialization entries to PHP.
   This can be done in the module startup and shutdown functions, using the macros
   <literal>REGISTER_INI_ENTRIES()</literal> and <literal>UNREGISTER_INI_ENTRIES()</literal>:
   <programlisting>
ZEND_MINIT_FUNCTION(mymodule)
{

    REGISTER_INI_ENTRIES();

}

ZEND_MSHUTDOWN_FUNCTION(mymodule)
{

    UNREGISTER_INI_ENTRIES();

}
   </programlisting>
  </para> 
 </sect1> 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->