1 | <HTML
|
---|
2 | ><HEAD
|
---|
3 | ><TITLE
|
---|
4 | >Initialization File Support</TITLE
|
---|
5 | ><META
|
---|
6 | NAME="GENERATOR"
|
---|
7 | CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
---|
8 | REL="HOME"
|
---|
9 | TITLE="Manuál PHP"
|
---|
10 | HREF="index.html"><LINK
|
---|
11 | REL="UP"
|
---|
12 | TITLE="Extending PHP 4.0"
|
---|
13 | HREF="zend.html"><LINK
|
---|
14 | REL="PREVIOUS"
|
---|
15 | TITLE="Calling User Functions"
|
---|
16 | HREF="zend.calling-user-functions.html"><LINK
|
---|
17 | REL="NEXT"
|
---|
18 | TITLE="Where to Go from Here"
|
---|
19 | HREF="zend.where-to-go.html"><META
|
---|
20 | HTTP-EQUIV="Content-type"
|
---|
21 | CONTENT="text/html; charset=ISO-8859-2"></HEAD
|
---|
22 | ><BODY
|
---|
23 | CLASS="chapter"
|
---|
24 | BGCOLOR="#FFFFFF"
|
---|
25 | TEXT="#000000"
|
---|
26 | LINK="#0000FF"
|
---|
27 | VLINK="#840084"
|
---|
28 | ALINK="#0000FF"
|
---|
29 | ><DIV
|
---|
30 | CLASS="NAVHEADER"
|
---|
31 | ><TABLE
|
---|
32 | SUMMARY="Header navigation table"
|
---|
33 | WIDTH="100%"
|
---|
34 | BORDER="0"
|
---|
35 | CELLPADDING="0"
|
---|
36 | CELLSPACING="0"
|
---|
37 | ><TR
|
---|
38 | ><TH
|
---|
39 | COLSPAN="3"
|
---|
40 | ALIGN="center"
|
---|
41 | >Manuál PHP</TH
|
---|
42 | ></TR
|
---|
43 | ><TR
|
---|
44 | ><TD
|
---|
45 | WIDTH="10%"
|
---|
46 | ALIGN="left"
|
---|
47 | VALIGN="bottom"
|
---|
48 | ><A
|
---|
49 | HREF="zend.calling-user-functions.html"
|
---|
50 | ACCESSKEY="P"
|
---|
51 | >Pøedcházející</A
|
---|
52 | ></TD
|
---|
53 | ><TD
|
---|
54 | WIDTH="80%"
|
---|
55 | ALIGN="center"
|
---|
56 | VALIGN="bottom"
|
---|
57 | ></TD
|
---|
58 | ><TD
|
---|
59 | WIDTH="10%"
|
---|
60 | ALIGN="right"
|
---|
61 | VALIGN="bottom"
|
---|
62 | ><A
|
---|
63 | HREF="zend.where-to-go.html"
|
---|
64 | ACCESSKEY="N"
|
---|
65 | >Dal¹í</A
|
---|
66 | ></TD
|
---|
67 | ></TR
|
---|
68 | ></TABLE
|
---|
69 | ><HR
|
---|
70 | ALIGN="LEFT"
|
---|
71 | WIDTH="100%"></DIV
|
---|
72 | ><DIV
|
---|
73 | CLASS="chapter"
|
---|
74 | ><H1
|
---|
75 | ><A
|
---|
76 | NAME="zend.ini-file-support"
|
---|
77 | >Kapitola 39. Initialization File Support</A
|
---|
78 | ></H1
|
---|
79 | ><P
|
---|
80 | > 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 | > To create an .ini section in your own module, use the
|
---|
87 | macros <TT
|
---|
88 | CLASS="literal"
|
---|
89 | >PHP_INI_BEGIN()</TT
|
---|
90 | > to mark the beginning of such a
|
---|
91 | section and <TT
|
---|
92 | CLASS="literal"
|
---|
93 | >PHP_INI_END()</TT
|
---|
94 | > to mark its end. In between you can
|
---|
95 | use <TT
|
---|
96 | CLASS="literal"
|
---|
97 | >PHP_INI_ENTRY()</TT
|
---|
98 | > to create entries.
|
---|
99 | <TABLE
|
---|
100 | BORDER="0"
|
---|
101 | BGCOLOR="#E0E0E0"
|
---|
102 | CELLPADDING="5"
|
---|
103 | ><TR
|
---|
104 | ><TD
|
---|
105 | ><PRE
|
---|
106 | CLASS="programlisting"
|
---|
107 | >PHP_INI_BEGIN()
|
---|
108 | PHP_INI_ENTRY("first_ini_entry", "has_string_value", PHP_INI_ALL, NULL)
|
---|
109 | PHP_INI_ENTRY("second_ini_entry", "2", PHP_INI_SYSTEM, OnChangeSecond)
|
---|
110 | PHP_INI_ENTRY("third_ini_entry", "xyz", PHP_INI_USER, NULL)
|
---|
111 | PHP_INI_END()</PRE
|
---|
112 | ></TD
|
---|
113 | ></TR
|
---|
114 | ></TABLE
|
---|
115 | >
|
---|
116 | The <TT
|
---|
117 | CLASS="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 | > The permissions are grouped into three
|
---|
127 | sections:<TT
|
---|
128 | CLASS="literal"
|
---|
129 | >PHP_INI_SYSTEM</TT
|
---|
130 | > allows a change only directly in
|
---|
131 | the <TT
|
---|
132 | CLASS="filename"
|
---|
133 | >php.ini</TT
|
---|
134 | > file; <TT
|
---|
135 | CLASS="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
|
---|
140 | CLASS="filename"
|
---|
141 | >.htaccess</TT
|
---|
142 | >; and <TT
|
---|
143 | CLASS="literal"
|
---|
144 | >PHP_INI_ALL</TT
|
---|
145 | > allows
|
---|
146 | changes to be made without restrictions. There's also a fourth level,
|
---|
147 | <TT
|
---|
148 | CLASS="literal"
|
---|
149 | >PHP_INI_PERDIR</TT
|
---|
150 | >, for which we couldn't verify its behavior
|
---|
151 | yet.
|
---|
152 | </P
|
---|
153 | ><P
|
---|
154 | > 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
|
---|
158 | CLASS="literal"
|
---|
159 | >PHP_INI_MH</TT
|
---|
160 | > macro:
|
---|
161 | <TABLE
|
---|
162 | BORDER="0"
|
---|
163 | BGCOLOR="#E0E0E0"
|
---|
164 | CELLPADDING="5"
|
---|
165 | ><TR
|
---|
166 | ><TD
|
---|
167 | ><PRE
|
---|
168 | CLASS="programlisting"
|
---|
169 | >PHP_INI_MH(OnChangeSecond); // handler for ini-entry "second_ini_entry"
|
---|
170 |
|
---|
171 | // specify ini-entries here
|
---|
172 |
|
---|
173 | PHP_INI_MH(OnChangeSecond)
|
---|
174 | {
|
---|
175 |
|
---|
176 | zend_printf("Message caught, our ini entry has been changed to %s<br>", 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
|
---|
187 | CLASS="envar"
|
---|
188 | >new_value</TT
|
---|
189 | >. When looking at the definition
|
---|
190 | of <TT
|
---|
191 | CLASS="literal"
|
---|
192 | >PHP_INI_MH</TT
|
---|
193 | >, you actually have a few parameters to use:
|
---|
194 | <TABLE
|
---|
195 | BORDER="0"
|
---|
196 | BGCOLOR="#E0E0E0"
|
---|
197 | CELLPADDING="5"
|
---|
198 | ><TR
|
---|
199 | ><TD
|
---|
200 | ><PRE
|
---|
201 | CLASS="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
|
---|
211 | CLASS="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
|
---|
217 | CLASS="literal"
|
---|
218 | >PHP_INI_ENTRY1</TT
|
---|
219 | > (allowing one additional
|
---|
220 | argument), <TT
|
---|
221 | CLASS="literal"
|
---|
222 | >PHP_INI_ENTRY2</TT
|
---|
223 | > (allowing two additional arguments),
|
---|
224 | and <TT
|
---|
225 | CLASS="literal"
|
---|
226 | >PHP_INI_ENTRY3</TT
|
---|
227 | > (allowing three additional
|
---|
228 | arguments).
|
---|
229 | </P
|
---|
230 | ><P
|
---|
231 | > 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 | > Access to initialization entries can also be handled with the macros
|
---|
239 | shown in <A
|
---|
240 | HREF="zend.ini-file-support.html#table.ini-macros"
|
---|
241 | >39-1</A
|
---|
242 | >.
|
---|
243 | </P
|
---|
244 | ><DIV
|
---|
245 | CLASS="table"
|
---|
246 | ><A
|
---|
247 | NAME="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
|
---|
254 | BORDER="1"
|
---|
255 | CLASS="CALSTABLE"
|
---|
256 | ><TBODY
|
---|
257 | ><TR
|
---|
258 | ><TD
|
---|
259 | WIDTH="38%"
|
---|
260 | ALIGN="LEFT"
|
---|
261 | VALIGN="MIDDLE"
|
---|
262 | >Macro</TD
|
---|
263 | ><TD
|
---|
264 | WIDTH="62%"
|
---|
265 | ALIGN="LEFT"
|
---|
266 | VALIGN="MIDDLE"
|
---|
267 | >Description</TD
|
---|
268 | ></TR
|
---|
269 | ><TR
|
---|
270 | ><TD
|
---|
271 | WIDTH="38%"
|
---|
272 | ALIGN="LEFT"
|
---|
273 | VALIGN="MIDDLE"
|
---|
274 | ><TT
|
---|
275 | CLASS="literal"
|
---|
276 | >INI_INT(name)</TT
|
---|
277 | ></TD
|
---|
278 | ><TD
|
---|
279 | WIDTH="62%"
|
---|
280 | ALIGN="LEFT"
|
---|
281 | VALIGN="MIDDLE"
|
---|
282 | >Returns the current value of
|
---|
283 | entry <TT
|
---|
284 | CLASS="literal"
|
---|
285 | >name</TT
|
---|
286 | > as integer (long).</TD
|
---|
287 | ></TR
|
---|
288 | ><TR
|
---|
289 | ><TD
|
---|
290 | WIDTH="38%"
|
---|
291 | ALIGN="LEFT"
|
---|
292 | VALIGN="MIDDLE"
|
---|
293 | ><TT
|
---|
294 | CLASS="literal"
|
---|
295 | >INI_FLT(name)</TT
|
---|
296 | ></TD
|
---|
297 | ><TD
|
---|
298 | WIDTH="62%"
|
---|
299 | ALIGN="LEFT"
|
---|
300 | VALIGN="MIDDLE"
|
---|
301 | >Returns the current value of
|
---|
302 | entry <TT
|
---|
303 | CLASS="literal"
|
---|
304 | >name</TT
|
---|
305 | > as float (double).</TD
|
---|
306 | ></TR
|
---|
307 | ><TR
|
---|
308 | ><TD
|
---|
309 | WIDTH="38%"
|
---|
310 | ALIGN="LEFT"
|
---|
311 | VALIGN="MIDDLE"
|
---|
312 | ><TT
|
---|
313 | CLASS="literal"
|
---|
314 | >INI_STR(name)</TT
|
---|
315 | ></TD
|
---|
316 | ><TD
|
---|
317 | WIDTH="62%"
|
---|
318 | ALIGN="LEFT"
|
---|
319 | VALIGN="MIDDLE"
|
---|
320 | >Returns the current value of
|
---|
321 | entry <TT
|
---|
322 | CLASS="literal"
|
---|
323 | >name</TT
|
---|
324 | > as string. <SPAN
|
---|
325 | CLASS="emphasis"
|
---|
326 | ><I
|
---|
327 | CLASS="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
|
---|
336 | WIDTH="38%"
|
---|
337 | ALIGN="LEFT"
|
---|
338 | VALIGN="MIDDLE"
|
---|
339 | ><TT
|
---|
340 | CLASS="literal"
|
---|
341 | >INI_BOOL(name)</TT
|
---|
342 | ></TD
|
---|
343 | ><TD
|
---|
344 | WIDTH="62%"
|
---|
345 | ALIGN="LEFT"
|
---|
346 | VALIGN="MIDDLE"
|
---|
347 | >Returns the current value of
|
---|
348 | entry <TT
|
---|
349 | CLASS="literal"
|
---|
350 | >name</TT
|
---|
351 | > as Boolean (defined as <TT
|
---|
352 | CLASS="envar"
|
---|
353 | >zend_bool</TT
|
---|
354 | >,
|
---|
355 | which currently means <TT
|
---|
356 | CLASS="envar"
|
---|
357 | >unsigned char</TT
|
---|
358 | >).</TD
|
---|
359 | ></TR
|
---|
360 | ><TR
|
---|
361 | ><TD
|
---|
362 | WIDTH="38%"
|
---|
363 | ALIGN="LEFT"
|
---|
364 | VALIGN="MIDDLE"
|
---|
365 | ><TT
|
---|
366 | CLASS="literal"
|
---|
367 | >INI_ORIG_INT(name)</TT
|
---|
368 | ></TD
|
---|
369 | ><TD
|
---|
370 | WIDTH="62%"
|
---|
371 | ALIGN="LEFT"
|
---|
372 | VALIGN="MIDDLE"
|
---|
373 | >Returns the original value of
|
---|
374 | entry <TT
|
---|
375 | CLASS="literal"
|
---|
376 | >name</TT
|
---|
377 | > as integer (long).</TD
|
---|
378 | ></TR
|
---|
379 | ><TR
|
---|
380 | ><TD
|
---|
381 | WIDTH="38%"
|
---|
382 | ALIGN="LEFT"
|
---|
383 | VALIGN="MIDDLE"
|
---|
384 | ><TT
|
---|
385 | CLASS="literal"
|
---|
386 | >INI_ORIG_FLT(name)</TT
|
---|
387 | ></TD
|
---|
388 | ><TD
|
---|
389 | WIDTH="62%"
|
---|
390 | ALIGN="LEFT"
|
---|
391 | VALIGN="MIDDLE"
|
---|
392 | >Returns the original value of
|
---|
393 | entry <TT
|
---|
394 | CLASS="literal"
|
---|
395 | >name</TT
|
---|
396 | > as float (double).</TD
|
---|
397 | ></TR
|
---|
398 | ><TR
|
---|
399 | ><TD
|
---|
400 | WIDTH="38%"
|
---|
401 | ALIGN="LEFT"
|
---|
402 | VALIGN="MIDDLE"
|
---|
403 | ><TT
|
---|
404 | CLASS="literal"
|
---|
405 | >INI_ORIG_STR(name)</TT
|
---|
406 | ></TD
|
---|
407 | ><TD
|
---|
408 | WIDTH="62%"
|
---|
409 | ALIGN="LEFT"
|
---|
410 | VALIGN="MIDDLE"
|
---|
411 | >Returns the original value of
|
---|
412 | entry <TT
|
---|
413 | CLASS="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
|
---|
421 | WIDTH="38%"
|
---|
422 | ALIGN="LEFT"
|
---|
423 | VALIGN="MIDDLE"
|
---|
424 | ><TT
|
---|
425 | CLASS="literal"
|
---|
426 | >INI_ORIG_BOOL(name)</TT
|
---|
427 | ></TD
|
---|
428 | ><TD
|
---|
429 | WIDTH="62%"
|
---|
430 | ALIGN="LEFT"
|
---|
431 | VALIGN="MIDDLE"
|
---|
432 | >Returns the original value of
|
---|
433 | entry <TT
|
---|
434 | CLASS="literal"
|
---|
435 | >name</TT
|
---|
436 | > as Boolean (defined as <TT
|
---|
437 | CLASS="envar"
|
---|
438 | >zend_bool</TT
|
---|
439 | >, which
|
---|
440 | currently means <TT
|
---|
441 | CLASS="envar"
|
---|
442 | >unsigned char</TT
|
---|
443 | >).</TD
|
---|
444 | ></TR
|
---|
445 | ></TBODY
|
---|
446 | ></TABLE
|
---|
447 | ></DIV
|
---|
448 | ><P
|
---|
449 | > 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
|
---|
452 | CLASS="literal"
|
---|
453 | >REGISTER_INI_ENTRIES()</TT
|
---|
454 | > and <TT
|
---|
455 | CLASS="literal"
|
---|
456 | >UNREGISTER_INI_ENTRIES()</TT
|
---|
457 | >:
|
---|
458 | <TABLE
|
---|
459 | BORDER="0"
|
---|
460 | BGCOLOR="#E0E0E0"
|
---|
461 | CELLPADDING="5"
|
---|
462 | ><TR
|
---|
463 | ><TD
|
---|
464 | ><PRE
|
---|
465 | CLASS="programlisting"
|
---|
466 | >ZEND_MINIT_FUNCTION(mymodule)
|
---|
467 | {
|
---|
468 |
|
---|
469 | REGISTER_INI_ENTRIES();
|
---|
470 |
|
---|
471 | }
|
---|
472 |
|
---|
473 | ZEND_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
|
---|
486 | CLASS="NAVFOOTER"
|
---|
487 | ><HR
|
---|
488 | ALIGN="LEFT"
|
---|
489 | WIDTH="100%"><TABLE
|
---|
490 | SUMMARY="Footer navigation table"
|
---|
491 | WIDTH="100%"
|
---|
492 | BORDER="0"
|
---|
493 | CELLPADDING="0"
|
---|
494 | CELLSPACING="0"
|
---|
495 | ><TR
|
---|
496 | ><TD
|
---|
497 | WIDTH="33%"
|
---|
498 | ALIGN="left"
|
---|
499 | VALIGN="top"
|
---|
500 | ><A
|
---|
501 | HREF="zend.calling-user-functions.html"
|
---|
502 | ACCESSKEY="P"
|
---|
503 | >Pøedcházející</A
|
---|
504 | ></TD
|
---|
505 | ><TD
|
---|
506 | WIDTH="34%"
|
---|
507 | ALIGN="center"
|
---|
508 | VALIGN="top"
|
---|
509 | ><A
|
---|
510 | HREF="index.html"
|
---|
511 | ACCESSKEY="H"
|
---|
512 | >Domù</A
|
---|
513 | ></TD
|
---|
514 | ><TD
|
---|
515 | WIDTH="33%"
|
---|
516 | ALIGN="right"
|
---|
517 | VALIGN="top"
|
---|
518 | ><A
|
---|
519 | HREF="zend.where-to-go.html"
|
---|
520 | ACCESSKEY="N"
|
---|
521 | >Dal¹í</A
|
---|
522 | ></TD
|
---|
523 | ></TR
|
---|
524 | ><TR
|
---|
525 | ><TD
|
---|
526 | WIDTH="33%"
|
---|
527 | ALIGN="left"
|
---|
528 | VALIGN="top"
|
---|
529 | >Calling User Functions</TD
|
---|
530 | ><TD
|
---|
531 | WIDTH="34%"
|
---|
532 | ALIGN="center"
|
---|
533 | VALIGN="top"
|
---|
534 | ><A
|
---|
535 | HREF="zend.html"
|
---|
536 | ACCESSKEY="U"
|
---|
537 | >Nahoru</A
|
---|
538 | ></TD
|
---|
539 | ><TD
|
---|
540 | WIDTH="33%"
|
---|
541 | ALIGN="right"
|
---|
542 | VALIGN="top"
|
---|
543 | >Where to Go from Here</TD
|
---|
544 | ></TR
|
---|
545 | ></TABLE
|
---|
546 | ></DIV
|
---|
547 | ></BODY
|
---|
548 | ></HTML
|
---|
549 | >
|
---|