source: www/manuals/PHP_manual/zend.ini-file-support.html@ 1

Last change on this file since 1 was 1, checked in by george, 17 years ago

Prvotní import všeho

File size: 9.4 KB
Line 
1<HTML
2><HEAD
3><TITLE
4>Initialization File Support</TITLE
5><META
6NAME="GENERATOR"
7CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
8REL="HOME"
9TITLE="Manuál PHP"
10HREF="index.html"><LINK
11REL="UP"
12TITLE="Extending PHP 4.0"
13HREF="zend.html"><LINK
14REL="PREVIOUS"
15TITLE="Calling User Functions"
16HREF="zend.calling-user-functions.html"><LINK
17REL="NEXT"
18TITLE="Where to Go from Here"
19HREF="zend.where-to-go.html"><META
20HTTP-EQUIV="Content-type"
21CONTENT="text/html; charset=ISO-8859-2"></HEAD
22><BODY
23CLASS="chapter"
24BGCOLOR="#FFFFFF"
25TEXT="#000000"
26LINK="#0000FF"
27VLINK="#840084"
28ALINK="#0000FF"
29><DIV
30CLASS="NAVHEADER"
31><TABLE
32SUMMARY="Header navigation table"
33WIDTH="100%"
34BORDER="0"
35CELLPADDING="0"
36CELLSPACING="0"
37><TR
38><TH
39COLSPAN="3"
40ALIGN="center"
41>Manuál PHP</TH
42></TR
43><TR
44><TD
45WIDTH="10%"
46ALIGN="left"
47VALIGN="bottom"
48><A
49HREF="zend.calling-user-functions.html"
50ACCESSKEY="P"
51>Pøedcházející</A
52></TD
53><TD
54WIDTH="80%"
55ALIGN="center"
56VALIGN="bottom"
57></TD
58><TD
59WIDTH="10%"
60ALIGN="right"
61VALIGN="bottom"
62><A
63HREF="zend.where-to-go.html"
64ACCESSKEY="N"
65>Dal¹í</A
66></TD
67></TR
68></TABLE
69><HR
70ALIGN="LEFT"
71WIDTH="100%"></DIV
72><DIV
73CLASS="chapter"
74><H1
75><A
76NAME="zend.ini-file-support"
77>Kapitola 39. Initialization File Support</A
78></H1
79><P
80>&#13; PHP 4 features a redesigned initialization file support. It's now
81 possible to specify default initialization entries directly in your code, read
82 and change these values at runtime, and create message handlers for change
83 notifications.
84 </P
85><P
86>&#13; To create an .ini section in your own module, use the
87 macros <TT
88CLASS="literal"
89>PHP_INI_BEGIN()</TT
90> to mark the beginning of such a
91 section and <TT
92CLASS="literal"
93>PHP_INI_END()</TT
94> to mark its end. In between you can
95 use <TT
96CLASS="literal"
97>PHP_INI_ENTRY()</TT
98> to create entries.
99<TABLE
100BORDER="0"
101BGCOLOR="#E0E0E0"
102CELLPADDING="5"
103><TR
104><TD
105><PRE
106CLASS="programlisting"
107>PHP_INI_BEGIN()
108PHP_INI_ENTRY("first_ini_entry", "has_string_value", PHP_INI_ALL, NULL)
109PHP_INI_ENTRY("second_ini_entry", "2", PHP_INI_SYSTEM, OnChangeSecond)
110PHP_INI_ENTRY("third_ini_entry", "xyz", PHP_INI_USER, NULL)
111PHP_INI_END()</PRE
112></TD
113></TR
114></TABLE
115>
116 The <TT
117CLASS="literal"
118>PHP_INI_ENTRY()</TT
119> macro accepts four
120 parameters: the entry name, the entry value, its change permissions, and a
121 pointer to a change-notification handler. Both entry name and value must be
122 specified as strings, regardless of whether they really are strings or
123 integers.
124 </P
125><P
126>&#13; The permissions are grouped into three
127 sections:<TT
128CLASS="literal"
129>PHP_INI_SYSTEM</TT
130> allows a change only directly in
131 the <TT
132CLASS="filename"
133>php.ini</TT
134> file; <TT
135CLASS="literal"
136>PHP_INI_USER</TT
137> allows
138 a change to be overridden by a user at runtime using additional
139 configuration files, such as <TT
140CLASS="filename"
141>.htaccess</TT
142>; and <TT
143CLASS="literal"
144>PHP_INI_ALL</TT
145> allows
146 changes to be made without restrictions. There's also a fourth level,
147 <TT
148CLASS="literal"
149>PHP_INI_PERDIR</TT
150>, for which we couldn't verify its behavior
151 yet.
152 </P
153><P
154>&#13; The fourth parameter consists of a pointer to a change-notification
155 handler. Whenever one of these initialization entries is changed, this handler
156 is called. Such a handler can be declared using the
157 <TT
158CLASS="literal"
159>PHP_INI_MH</TT
160> macro:
161 <TABLE
162BORDER="0"
163BGCOLOR="#E0E0E0"
164CELLPADDING="5"
165><TR
166><TD
167><PRE
168CLASS="programlisting"
169>PHP_INI_MH(OnChangeSecond); // handler for ini-entry "second_ini_entry"
170
171// specify ini-entries here
172
173PHP_INI_MH(OnChangeSecond)
174{
175
176 zend_printf("Message caught, our ini entry has been changed to %s&#60;br&#62;", new_value);
177
178 return(SUCCESS);
179
180}</PRE
181></TD
182></TR
183></TABLE
184>
185 The new value is given to the change handler as string in
186 the variable <TT
187CLASS="envar"
188>new_value</TT
189>. When looking at the definition
190 of <TT
191CLASS="literal"
192>PHP_INI_MH</TT
193>, you actually have a few parameters to use:
194 <TABLE
195BORDER="0"
196BGCOLOR="#E0E0E0"
197CELLPADDING="5"
198><TR
199><TD
200><PRE
201CLASS="programlisting"
202>#define PHP_INI_MH(name) int name(php_ini_entry *entry, char *new_value,
203 uint new_value_length, void *mh_arg1,
204 void *mh_arg2, void *mh_arg3)</PRE
205></TD
206></TR
207></TABLE
208>
209 All these definitions can be found
210 in <TT
211CLASS="filename"
212>php_ini.h</TT
213>. Your message handler will have access to a
214 structure that contains the full entry, the new value, its length, and three
215 optional arguments. These optional arguments can be specified with the additional
216 macros <TT
217CLASS="literal"
218>PHP_INI_ENTRY1</TT
219> (allowing one additional
220 argument), <TT
221CLASS="literal"
222>PHP_INI_ENTRY2</TT
223> (allowing two additional arguments),
224 and <TT
225CLASS="literal"
226>PHP_INI_ENTRY3</TT
227> (allowing three additional
228 arguments).
229 </P
230><P
231>&#13; The change-notification handlers should be used to cache initialization
232 entries locally for faster access or to perform certain tasks that are
233 required if a value changes. For example, if a constant connection to a
234 certain host is required by a module and someone changes the hostname,
235 automatically terminate the old connection and attempt a new one.
236 </P
237><P
238>&#13; Access to initialization entries can also be handled with the macros
239 shown in <A
240HREF="zend.ini-file-support.html#table.ini-macros"
241>39-1</A
242>.
243 </P
244><DIV
245CLASS="table"
246><A
247NAME="table.ini-macros"
248></A
249><P
250><B
251>Tabulka 39-1. Macros to Access Initialization Entries in PHP</B
252></P
253><TABLE
254BORDER="1"
255CLASS="CALSTABLE"
256><TBODY
257><TR
258><TD
259WIDTH="38%"
260ALIGN="LEFT"
261VALIGN="MIDDLE"
262>Macro</TD
263><TD
264WIDTH="62%"
265ALIGN="LEFT"
266VALIGN="MIDDLE"
267>Description</TD
268></TR
269><TR
270><TD
271WIDTH="38%"
272ALIGN="LEFT"
273VALIGN="MIDDLE"
274><TT
275CLASS="literal"
276>INI_INT(name)</TT
277></TD
278><TD
279WIDTH="62%"
280ALIGN="LEFT"
281VALIGN="MIDDLE"
282>Returns the current value of
283 entry <TT
284CLASS="literal"
285>name</TT
286> as integer (long).</TD
287></TR
288><TR
289><TD
290WIDTH="38%"
291ALIGN="LEFT"
292VALIGN="MIDDLE"
293><TT
294CLASS="literal"
295>INI_FLT(name)</TT
296></TD
297><TD
298WIDTH="62%"
299ALIGN="LEFT"
300VALIGN="MIDDLE"
301>Returns the current value of
302 entry <TT
303CLASS="literal"
304>name</TT
305> as float (double).</TD
306></TR
307><TR
308><TD
309WIDTH="38%"
310ALIGN="LEFT"
311VALIGN="MIDDLE"
312><TT
313CLASS="literal"
314>INI_STR(name)</TT
315></TD
316><TD
317WIDTH="62%"
318ALIGN="LEFT"
319VALIGN="MIDDLE"
320>Returns the current value of
321 entry <TT
322CLASS="literal"
323>name</TT
324> as string. <SPAN
325CLASS="emphasis"
326><I
327CLASS="emphasis"
328>Note:</I
329></SPAN
330> This string is not duplicated, but
331 instead points to internal data. Further access requires duplication to local
332 memory.</TD
333></TR
334><TR
335><TD
336WIDTH="38%"
337ALIGN="LEFT"
338VALIGN="MIDDLE"
339><TT
340CLASS="literal"
341>INI_BOOL(name)</TT
342></TD
343><TD
344WIDTH="62%"
345ALIGN="LEFT"
346VALIGN="MIDDLE"
347>Returns the current value of
348 entry <TT
349CLASS="literal"
350>name</TT
351> as Boolean (defined as <TT
352CLASS="envar"
353>zend_bool</TT
354>,
355 which currently means <TT
356CLASS="envar"
357>unsigned char</TT
358>).</TD
359></TR
360><TR
361><TD
362WIDTH="38%"
363ALIGN="LEFT"
364VALIGN="MIDDLE"
365><TT
366CLASS="literal"
367>INI_ORIG_INT(name)</TT
368></TD
369><TD
370WIDTH="62%"
371ALIGN="LEFT"
372VALIGN="MIDDLE"
373>Returns the original value of
374 entry <TT
375CLASS="literal"
376>name</TT
377> as integer (long).</TD
378></TR
379><TR
380><TD
381WIDTH="38%"
382ALIGN="LEFT"
383VALIGN="MIDDLE"
384><TT
385CLASS="literal"
386>INI_ORIG_FLT(name)</TT
387></TD
388><TD
389WIDTH="62%"
390ALIGN="LEFT"
391VALIGN="MIDDLE"
392>Returns the original value of
393 entry <TT
394CLASS="literal"
395>name</TT
396> as float (double).</TD
397></TR
398><TR
399><TD
400WIDTH="38%"
401ALIGN="LEFT"
402VALIGN="MIDDLE"
403><TT
404CLASS="literal"
405>INI_ORIG_STR(name)</TT
406></TD
407><TD
408WIDTH="62%"
409ALIGN="LEFT"
410VALIGN="MIDDLE"
411>Returns the original value of
412 entry <TT
413CLASS="literal"
414>name</TT
415> as string. Note: This string is not duplicated, but
416 instead points to internal data. Further access requires duplication to local
417 memory.</TD
418></TR
419><TR
420><TD
421WIDTH="38%"
422ALIGN="LEFT"
423VALIGN="MIDDLE"
424><TT
425CLASS="literal"
426>INI_ORIG_BOOL(name)</TT
427></TD
428><TD
429WIDTH="62%"
430ALIGN="LEFT"
431VALIGN="MIDDLE"
432>Returns the original value of
433 entry <TT
434CLASS="literal"
435>name</TT
436> as Boolean (defined as <TT
437CLASS="envar"
438>zend_bool</TT
439>, which
440 currently means <TT
441CLASS="envar"
442>unsigned char</TT
443>).</TD
444></TR
445></TBODY
446></TABLE
447></DIV
448><P
449>&#13; Finally, you have to introduce your initialization entries to PHP.
450 This can be done in the module startup and shutdown functions, using the macros
451 <TT
452CLASS="literal"
453>REGISTER_INI_ENTRIES()</TT
454> and <TT
455CLASS="literal"
456>UNREGISTER_INI_ENTRIES()</TT
457>:
458 <TABLE
459BORDER="0"
460BGCOLOR="#E0E0E0"
461CELLPADDING="5"
462><TR
463><TD
464><PRE
465CLASS="programlisting"
466>ZEND_MINIT_FUNCTION(mymodule)
467{
468
469 REGISTER_INI_ENTRIES();
470
471}
472
473ZEND_MSHUTDOWN_FUNCTION(mymodule)
474{
475
476 UNREGISTER_INI_ENTRIES();
477
478}</PRE
479></TD
480></TR
481></TABLE
482>
483 </P
484></DIV
485><DIV
486CLASS="NAVFOOTER"
487><HR
488ALIGN="LEFT"
489WIDTH="100%"><TABLE
490SUMMARY="Footer navigation table"
491WIDTH="100%"
492BORDER="0"
493CELLPADDING="0"
494CELLSPACING="0"
495><TR
496><TD
497WIDTH="33%"
498ALIGN="left"
499VALIGN="top"
500><A
501HREF="zend.calling-user-functions.html"
502ACCESSKEY="P"
503>Pøedcházející</A
504></TD
505><TD
506WIDTH="34%"
507ALIGN="center"
508VALIGN="top"
509><A
510HREF="index.html"
511ACCESSKEY="H"
512>Domù</A
513></TD
514><TD
515WIDTH="33%"
516ALIGN="right"
517VALIGN="top"
518><A
519HREF="zend.where-to-go.html"
520ACCESSKEY="N"
521>Dal¹í</A
522></TD
523></TR
524><TR
525><TD
526WIDTH="33%"
527ALIGN="left"
528VALIGN="top"
529>Calling User Functions</TD
530><TD
531WIDTH="34%"
532ALIGN="center"
533VALIGN="top"
534><A
535HREF="zend.html"
536ACCESSKEY="U"
537>Nahoru</A
538></TD
539><TD
540WIDTH="33%"
541ALIGN="right"
542VALIGN="top"
543>Where to Go from Here</TD
544></TR
545></TABLE
546></DIV
547></BODY
548></HTML
549>
Note: See TracBrowser for help on using the repository browser.