reference/filesystem/functions/parse-ini-file.xml
a5346daf2bb2fab250fa03f0f6639a408d0b2240
...
...
@@ -1,6 +1,6 @@
1
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
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>
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>
...
...
@@ -70,62 +72,6 @@
70
72
</para>
71
73
</refsect1>
72
74

73
-
74
-
<refsect1 role="changelog">
75
-
&reftitle.changelog;
76
-
<para>
77
-
<informaltable>
78
-
<tgroup cols="2">
79
-
<thead>
80
-
<row>
81
-
<entry>&Version;</entry>
82
-
<entry>&Description;</entry>
83
-
</row>
84
-
</thead>
85
-
<tbody>
86
-
<row>
87
-
<entry>7.0.0</entry>
88
-
<entry>
89
-
Hash marks (<literal>#</literal>) are no longer recognized as comments.
90
-
</entry>
91
-
</row>
92
-
<row>
93
-
<entry>5.6.1</entry>
94
-
<entry>
95
-
Added new <constant>INI_SCANNER_TYPED</constant> mode.
96
-
</entry>
97
-
</row>
98
-
<row>
99
-
<entry>5.3.0</entry>
100
-
<entry>
101
-
Added optional <parameter>scanner_mode</parameter> parameter.
102
-
Single quotes may now be used around variable assignments.
103
-
Hash marks (<literal>#</literal>) should no longer be used as comments
104
-
and will throw a deprecation warning if used.
105
-
</entry>
106
-
</row>
107
-
<row>
108
-
<entry>5.2.7</entry>
109
-
<entry>
110
-
On syntax error this function will return &false; rather than an empty
111
-
array.
112
-
</entry>
113
-
</row>
114
-
<row>
115
-
<entry>5.2.4</entry>
116
-
<entry>
117
-
Keys and section names consisting of numbers are now evaluated as PHP
118
-
<link linkend="language.types.integer">integers</link> thus numbers
119
-
starting by 0 are evaluated as octals and numbers starting by 0x are
120
-
evaluated as hexadecimals.
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>
...
...
@@ -159,10 +105,11 @@ urls[git] = "http://git.php.net"
159
105
<example>
160
106
<title><function>parse_ini_file</function> example</title>
161
107
<para>
162
-
<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
163
110
in the ini file so if you define a constant as an ini value before
164
111
running <function>parse_ini_file</function>, it will be integrated into
165
-
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:
166
113
</para>
167
114
<programlisting role="php">
168
115
<![CDATA[
...
...
@@ -256,8 +203,7 @@ function yesno($expression)
256
203
return($expression ? 'Yes' : 'No');
257
204
}
258
205

259
-
// Get the path to php.ini using the php_ini_loaded_file()
260
-
// function available as of PHP 5.2.4
206
+
// Get the path to php.ini using the php_ini_loaded_file() function
261
207
$ini_path = php_ini_loaded_file();
262
208

263
209
// Parse php.ini
...
...
@@ -279,6 +225,94 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
279
225
</screen>
280
226
</example>
281
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>
282
316
</refsect1>
283
317

284
318
<refsect1 role="notes">
...
...
@@ -306,7 +340,7 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
306
340
Values <literal>null</literal>, <literal>off</literal>, <literal>no</literal> and
307
341
<literal>false</literal> result in <literal>""</literal>, and values
308
342
<literal>on</literal>, <literal>yes</literal> and <literal>true</literal> result
309
-
in <literal>"1"</literal>, unless <constant>INI_SCANNER_TYPED</constant> mode is used (as of PHP 5.6.1).
343
+
in <literal>"1"</literal>, unless <constant>INI_SCANNER_TYPED</constant> mode is used.
310
344
Characters <literal>?{}|&amp;~!()^"</literal> must not be used anywhere in
311
345
the key and have a special meaning in the value.
312
346
</simpara>
...
...
@@ -320,6 +354,13 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
320
354
it is ignored.
321
355
</para>
322
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>
323
364
</refsect1>
324
365
325
366
<refsect1 role="seealso">
...
...
@@ -332,7 +373,6 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
332
373
</refsect1>
333
374

334
375
</refentry>
335
-

336
376
<!-- Keep this comment at the end of the file
337
377
Local variables:
338
378
mode: sgml
339
379



Tools (German Manual)