reference/filesystem/functions/parse-ini-file.xml
a5346daf2bb2fab250fa03f0f6639a408d0b2240
...
...
@@ -1,6 +1,6 @@
1
-
<?xml version="1.0" encoding="UTF-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.parse-ini-file">
3
+
<refentry xml:id="function.parse-ini-file" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>parse_ini_file</refname>
6
6
<refpurpose>Parse a configuration file</refpurpose>
...
...
@@ -9,10 +9,10 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>array</type><methodname>parse_ini_file</methodname>
12
+
<type class="union"><type>array</type><type>false</type></type><methodname>parse_ini_file</methodname>
13
13
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
14
-
<methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter><initializer>false</initializer></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>scanner_mode</parameter><initializer>INI_SCANNER_NORMAL</initializer></methodparam>
14
+
<methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter><initializer>&false;</initializer></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>scanner_mode</parameter><initializer><constant>INI_SCANNER_NORMAL</constant></initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
<function>parse_ini_file</function> loads in the
...
...
@@ -32,7 +32,9 @@
32
32
<term><parameter>filename</parameter></term>
33
33
<listitem>
34
34
<para>
35
-
The filename of the ini file being parsed.
35
+
The filename of the ini file being parsed. If a relative path is used,
36
+
it is evaluated relative to the current working directory, then the
37
+
<link linkend="ini.include-path">include_path</link>.
36
38
</para>
37
39
</listitem>
38
40
</varlistentry>
...
...
@@ -55,6 +57,7 @@
55
57
<constant>INI_SCANNER_RAW</constant>. If <constant>INI_SCANNER_RAW</constant>
56
58
is supplied, then option values will not be parsed.
57
59
</para>
60
+
&ini.scanner.typed;
58
61
</listitem>
59
62
</varlistentry>
60
63
</variablelist>
...
...
@@ -69,63 +72,6 @@
69
72
</para>
70
73
</refsect1>
71
74

72
-
73
-
<refsect1 role="changelog">
74
-
&reftitle.changelog;
75
-
<para>
76
-
<informaltable>
77
-
<tgroup cols="2">
78
-
<thead>
79
-
<row>
80
-
<entry>&Version;</entry>
81
-
<entry>&Description;</entry>
82
-
</row>
83
-
</thead>
84
-
<tbody>
85
-
<row>
86
-
<entry>5.3.0</entry>
87
-
<entry>
88
-
Added optional <parameter>scanner_mode</parameter> parameter.
89
-
Single quotes may now be used around variable assignments.
90
-
Hash marks (<literal>#</literal>) may no longer be used as comments
91
-
and will throw a deprecation warning if used.
92
-
</entry>
93
-
</row>
94
-
<row>
95
-
<entry>5.2.7</entry>
96
-
<entry>
97
-
On syntax error this function will return &false; rather than an empty
98
-
array.
99
-
</entry>
100
-
</row>
101
-
<row>
102
-
<entry>5.2.4</entry>
103
-
<entry>
104
-
Keys and section names consisting of numbers are now evaluated as PHP
105
-
<link linkend="language.types.integer">integers</link> thus numbers
106
-
starting by 0 are evaluated as octals and numbers starting by 0x are
107
-
evaluated as hexadecimals.
108
-
</entry>
109
-
</row>
110
-
<row>
111
-
<entry>5.0.0</entry>
112
-
<entry>
113
-
Values enclosed in double quotes can contain new lines.
114
-
</entry>
115
-
</row>
116
-
<row>
117
-
<entry>4.2.1</entry>
118
-
<entry>
119
-
This function is now affected by &safemode;
120
-
and <link linkend="ini.open-basedir">open_basedir</link>.
121
-
</entry>
122
-
</row>
123
-
</tbody>
124
-
</tgroup>
125
-
</informaltable>
126
-
</para>
127
-
</refsect1>
128
-

129
75
<refsect1 role="examples">
130
76
&reftitle.examples;
131
77
<para>
...
...
@@ -150,16 +96,20 @@ phpversion[] = "5.0"
150
96
phpversion[] = "5.1"
151
97
phpversion[] = "5.2"
152
98
phpversion[] = "5.3"
99
+

100
+
urls[svn] = "http://svn.php.net"
101
+
urls[git] = "http://git.php.net"
153
102
]]>
154
103
</programlisting>
155
104
</example>
156
105
<example>
157
106
<title><function>parse_ini_file</function> example</title>
158
107
<para>
159
-
<link linkend="language.constants">Constants</link> may also be parsed
108
+
<link linkend="language.constants">Constants</link> (but not "magic constants" like <constant>__FILE__</constant>)
109
+
may also be parsed
160
110
in the ini file so if you define a constant as an ini value before
161
111
running <function>parse_ini_file</function>, it will be integrated into
162
-
the results. Only ini values are evaluated. For example:
112
+
the results. Only ini values are evaluated, and the value must be just the constant. For example:
163
113
</para>
164
114
<programlisting role="php">
165
115
<![CDATA[
...
...
@@ -196,6 +146,12 @@ Array
196
146
[3] => 5.3
197
147
)
198
148

149
+
[urls] => Array
150
+
(
151
+
[svn] => http://svn.php.net
152
+
[git] => http://git.php.net
153
+
)
154
+

199
155
)
200
156
Array
201
157
(
...
...
@@ -222,6 +178,12 @@ Array
222
178
[3] => 5.3
223
179
)
224
180

181
+
[urls] => Array
182
+
(
183
+
[svn] => http://svn.php.net
184
+
[git] => http://git.php.net
185
+
)
186
+

225
187
)
226
188

227
189
)
...
...
@@ -241,8 +203,7 @@ function yesno($expression)
241
203
return($expression ? 'Yes' : 'No');
242
204
}
243
205

244
-
// Get the path to php.ini using the php_ini_loaded_file()
245
-
// function available as of PHP 5.2.4
206
+
// Get the path to php.ini using the php_ini_loaded_file() function
246
207
$ini_path = php_ini_loaded_file();
247
208

248
209
// Parse php.ini
...
...
@@ -264,6 +225,94 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
264
225
</screen>
265
226
</example>
266
227
</para>
228
+
<para>
229
+
<example>
230
+
<title>Value Interpolation</title>
231
+
<para>
232
+
In addition to evaluating constants, certain characters have special meaning in an ini value.
233
+
Additionally, environment variables and previously defined configuration options (see <function>get_cfg_var</function>) may be read using
234
+
<code>${}</code> syntax.
235
+
</para>
236
+
<programlisting>
237
+
<![CDATA[
238
+
; | is used for bitwise OR
239
+
three = 2|3
240
+

241
+
; & is used for bitwise AND
242
+
four = 6&5
243
+

244
+
; ^ is used for bitwise XOR
245
+
five = 3^6
246
+

247
+
; ~ is used for bitwise negate
248
+
negative_two = ~1
249
+

250
+
; () is used for grouping
251
+
seven = (8|7)&(6|5)
252
+

253
+
; Interpolate the PATH environment variable
254
+
path = ${PATH}
255
+

256
+
; Interpolate the configuration option 'memory_limit'
257
+
configured_memory_limit = ${memory_limit}
258
+

259
+
]]>
260
+
</programlisting>
261
+
</example>
262
+
</para>
263
+
<para>
264
+
<example>
265
+
<title>Escaping Characters</title>
266
+
<para>
267
+
Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix.
268
+
First of all, these are the double quote <code>"</code> as the boundary marker, and the backslash <code>\</code> itself
269
+
(if followed by one of the special characters):
270
+
</para>
271
+
<programlisting>
272
+
<![CDATA[
273
+
quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
274
+
hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote
275
+
]]>
276
+
</programlisting>
277
+
<para>
278
+
There is an exception made for Windows-like paths: it's possible to not escape trailing backslash
279
+
if the quoted string is directly followed by a linebreak:
280
+
</para>
281
+
<programlisting>
282
+
<![CDATA[
283
+
save_path = "C:\Temp\"
284
+
]]>
285
+
</programlisting>
286
+
<para>
287
+
If one does need to escape double quote followed by linebreak in a multiline value,
288
+
it's possible to use value concatenation in the following way
289
+
(there is one double-quoted string directly followed by another one):
290
+
</para>
291
+
<programlisting>
292
+
<![CDATA[
293
+
long_text = "Lorem \"ipsum\"""
294
+
dolor" ; Results in: Lorem "ipsum"\n dolor
295
+
]]>
296
+
</programlisting>
297
+
<para>
298
+
Another character with special meaning is <code>$</code> (the dollar sign).
299
+
It must be escaped if followed by the open curly brace:
300
+
</para>
301
+
<programlisting>
302
+
<![CDATA[
303
+
code = "\${test}"
304
+
]]>
305
+
</programlisting>
306
+
<para>
307
+
Escaping characters is not supported in the <constant>INI_SCANNER_RAW</constant> mode
308
+
(in this mode all characters are processed "as is").
309
+
</para>
310
+
<para>
311
+
Note that the ini parser doesn't support standard escape sequences (<code>\n</code>, <code>\t</code>, etc.).
312
+
If necessary, post-process the result of <function>parse_ini_file</function> with <function>stripcslashes</function> function.
313
+
</para>
314
+
</example>
315
+
</para>
267
316
</refsect1>
268
317

269
318
<refsect1 role="notes">
...
...
@@ -285,12 +334,33 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
285
334
<note>
286
335
<simpara>
287
336
There are reserved words which must not be used as keys for
288
-
ini files. These include: null, yes, no, true, false, on, off, none.
289
-
Values null, no and false results in "", yes and true results in "1".
290
-
Characters <literal>?{}|&amp;~![()^"</literal> must not be used anywhere in
337
+
ini files. These include: <literal>null</literal>, <literal>yes</literal>,
338
+
<literal>no</literal>, <literal>true</literal>, <literal>false</literal>,
339
+
<literal>on</literal>, <literal>off</literal>, <literal>none</literal>.
340
+
Values <literal>null</literal>, <literal>off</literal>, <literal>no</literal> and
341
+
<literal>false</literal> result in <literal>""</literal>, and values
342
+
<literal>on</literal>, <literal>yes</literal> and <literal>true</literal> result
343
+
in <literal>"1"</literal>, unless <constant>INI_SCANNER_TYPED</constant> mode is used.
344
+
Characters <literal>?{}|&amp;~!()^"</literal> must not be used anywhere in
291
345
the key and have a special meaning in the value.
292
346
</simpara>
293
347
</note>
348
+
<note>
349
+
<para>
350
+
Entries without an equal sign are ignored. For example, "foo"
351
+
is ignored whereas "bar =" is parsed and added with an empty
352
+
value. For example, MySQL has a "no-auto-rehash" setting
353
+
in <filename>my.cnf</filename> that does not take a value, so
354
+
it is ignored.
355
+
</para>
356
+
</note>
357
+
<note>
358
+
<para>
359
+
ini files are generally treated as plain text by web servers and thus served to browsers if requested.
360
+
That means for security you must either keep your ini files outside of your docroot or reconfigure your
361
+
web server to not serve them. Failure to do either of those may introduce a security risk.
362
+
</para>
363
+
</note>
294
364
</refsect1>
295
365
296
366
<refsect1 role="seealso">
...
...
@@ -303,7 +373,6 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
303
373
</refsect1>
304
374

305
375
</refentry>
306
-

307
376
<!-- Keep this comment at the end of the file
308
377
Local variables:
309
378
mode: sgml
310
379



Tools (Chinese (Simplified) Manual)