1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297078 $ -->
<!-- $Id: ini-file-support.xml 297078 2010-03-29 16:25:51Z degeberg $ -->
<sect2 xml:id="internals2.ze1.zendapi.ini-file-support" xmlns="http://docbook.org/ns/docbook">
<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 role="c">
<![CDATA[
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 role="c">
<![CDATA[
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);
}
]]>
</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 role="c">
<![CDATA[
#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="internals2.ze1.zendapi.table.ini-macros"/>.
</para>
<table xml:id="internals2.ze1.zendapi.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 role="c">
<![CDATA[
ZEND_MINIT_FUNCTION(mymodule)
{
REGISTER_INI_ENTRIES();
}
ZEND_MSHUTDOWN_FUNCTION(mymodule)
{
UNREGISTER_INI_ENTRIES();
}
]]>
</programlisting>
</para>
</sect2>
<!-- 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:"~/.phpdoc/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
-->
|
