install/ini.xml
15841d188475e59c105f57c9022873f2cd7467b5
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3
+
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<title>Runtime Configuration</title>
5
5

6
6
<sect1 xml:id="configuration.file">
...
...
@@ -19,26 +19,31 @@
19
19
<listitem>
20
20
<simpara>
21
21
SAPI module specific location (<literal>PHPIniDir</literal> directive
22
-
in Apache 2, <literal>-c</literal> command line option in CGI and CLI,
23
-
<literal>php_ini</literal> parameter in NSAPI,
24
-
<literal>PHP_INI_PATH</literal> environment variable in THTTPD)
22
+
in Apache 2, <literal>-c</literal> command line option in CGI and CLI)
25
23
</simpara>
26
24
</listitem>
27
25
<listitem>
28
26
<simpara>
29
-
The <varname>PHPRC</varname> environment variable. Before PHP 5.2.0,
30
-
this was checked after the registry key mentioned below.
27
+
The <varname>PHPRC</varname> environment variable.
31
28
</simpara>
32
29
</listitem>
33
30
<listitem>
34
31
<simpara>
35
-
As of PHP 5.2.0, the location of the <literal>php.ini</literal> file
36
-
can be set for different versions of PHP. The following registry keys
32
+
The location of the <literal>php.ini</literal> file
33
+
can be set for different versions of PHP. The root of the registry keys depends on 32- or 64-bitness of the installed OS and PHP.
34
+
For 32-bit PHP on a 32-bit OS or a 64-bit PHP on a 64-bit OS use <literal>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> for 32-bit version of PHP on a 64-bit OS use <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>] instead.
35
+
For same bitness installation the following registry keys
37
36
are examined in order:
38
37
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
39
38
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> and
40
39
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, where
41
-
x, y and z mean the PHP major, minor and release versions. If there is a
40
+
x, y and z mean the PHP major, minor and release versions.
41
+
For 32 bit versions of PHP on a 64 bit OS the following registry keys are examined in order:
42
+
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
43
+
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> and
44
+
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, where
45
+
x, y and z mean the PHP major, minor and release versions.
46
+
If there is a
42
47
value for <literal>IniFilePath</literal> in any of these keys, the first
43
48
one found will be used as the location of the <literal>php.ini</literal>
44
49
(Windows only).
...
...
@@ -46,7 +51,8 @@
46
51
</listitem>
47
52
<listitem>
48
53
<simpara>
49
-
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>, value of
54
+
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> or
55
+
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, value of
50
56
<literal>IniFilePath</literal> (Windows only).
51
57
</simpara>
52
58
</listitem>
...
...
@@ -130,20 +136,73 @@ include_path = ".;c:\php\lib"
130
136
</example>
131
137
</para>
132
138
<para>
133
-
Since PHP 5.1.0, it is possible to refer to existing .ini variables from
139
+
It is possible to refer to existing .ini variables from
134
140
within .ini files. Example: <literal>open_basedir = ${open_basedir}
135
141
":/new/dir"</literal>.
136
142
</para>
143
+
<sect2 xml:id="configuration.file.scan">
144
+
<title>Scan directories</title>
145
+

146
+
<para>
147
+
It is possible to configure PHP to scan for .ini files in a directory
148
+
after reading &php.ini;. This can be done at compile time by setting the
149
+
<option role="configure">--with-config-file-scan-dir</option> option.
150
+
The scan directory can then be overridden at run time
151
+
by setting the <varname>PHP_INI_SCAN_DIR</varname> environment variable.
152
+
</para>
153
+

154
+
<para>
155
+
It is possible to scan multiple directories by separating them with the
156
+
platform-specific path separator (<literal>;</literal> on Windows, NetWare
157
+
and RISC OS; <literal>:</literal> on all other platforms; the value PHP is
158
+
using is available as the <constant>PATH_SEPARATOR</constant> constant).
159
+
If a blank directory is given in <varname>PHP_INI_SCAN_DIR</varname>, PHP
160
+
will also scan the directory given at compile time via
161
+
<option role="configure">--with-config-file-scan-dir</option>.
162
+
</para>
163
+

164
+
<para>
165
+
Within each directory, PHP will scan all files ending in
166
+
<literal>.ini</literal> in alphabetical order. A list of the files that
167
+
were loaded, and in what order, is available by calling
168
+
<function>php_ini_scanned_files</function>, or by running PHP with the
169
+
<option>--ini</option> option.
170
+
</para>
171
+

172
+
<informalexample>
173
+
<screen>
174
+
<![CDATA[
175
+
Assuming PHP is configured with --with-config-file-scan-dir=/etc/php.d,
176
+
and that the path separator is :...
177
+

178
+
$ php
179
+
PHP will load all files in /etc/php.d/*.ini as configuration files.
180
+

181
+
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
182
+
PHP will load all files in /usr/local/etc/php.d/*.ini as
183
+
configuration files.
184
+

185
+
$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
186
+
PHP will load all files in /etc/php.d/*.ini, then
187
+
/usr/local/etc/php.d/*.ini as configuration files.
188
+

189
+
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
190
+
PHP will load all files in /usr/local/etc/php.d/*.ini, then
191
+
/etc/php.d/*.ini as configuration files.
192
+
]]>
193
+
</screen>
194
+
</informalexample>
195
+
</sect2>
137
196
</sect1>
138
197

139
198
<sect1 xml:id="configuration.file.per-user">
140
199
<title>.user.ini files</title>
141
200

142
201
<simpara>
143
-
Since PHP 5.3.0, PHP includes support for configuration INI files on a
202
+
PHP includes support for configuration INI files on a
144
203
per-directory basis. These files are processed <emphasis>only</emphasis> by
145
204
the CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner
146
-
extension. If you are using Apache, use &htaccess; files for the same
205
+
extension. If you are running PHP as Apache module, use &htaccess; files for the same
147
206
effect.
148
207
</simpara>
149
208

...
...
@@ -156,30 +215,26 @@ include_path = ".;c:\php\lib"
156
215
</simpara>
157
216
<simpara>
158
217
Only INI settings with the
159
-
modes <constant>PHP_INI_PERDIR</constant> and
160
-
<constant>PHP_INI_USER</constant> will be recognized in .user.ini-style INI
218
+
modes <constant>INI_PERDIR</constant> and
219
+
<constant>INI_USER</constant> will be recognized in .user.ini-style INI
161
220
files.
162
221
</simpara>
163
222

164
223
<simpara>
165
224
Two new INI directives,
166
-
<literal>user_ini.filename</literal> and
167
-
<literal>user_ini.cache_ttl</literal>
168
-
<!--
169
-
<link linkend="ini.user-ini.filename">user_ini.filename</link> and
170
-
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
171
-
-->
225
+
<link linkend="ini.user-ini.filename">user_ini.filename</link> and
226
+
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
172
227
control the use of user INI files.
173
228
</simpara>
174
229

175
230
<simpara>
176
-
<literal>user_ini.filename</literal> sets the name of the file PHP looks for
231
+
<link linkend="ini.user-ini.filename">user_ini.filename</link> sets the name of the file PHP looks for
177
232
in each directory; if set to an empty string, PHP doesn't scan at all. The
178
233
default is <literal>.user.ini</literal>.
179
234
</simpara>
180
235

181
236
<simpara>
182
-
<literal>user_ini.cache_ttl</literal> controls how often user INI files are
237
+
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> controls how often user INI files are
183
238
re-read. The default is 300 seconds (5 minutes).
184
239
</simpara>
185
240
</sect1>
...
...
@@ -198,49 +253,16 @@ include_path = ".;c:\php\lib"
198
253
<para>
199
254
For example, the
200
255
<link linkend="ini.output-buffering">output_buffering</link> setting
201
-
is <literal>PHP_INI_PERDIR</literal> therefore it may not be set using
256
+
is <constant>INI_PERDIR</constant> therefore it may not be set using
202
257
<function>ini_set</function>. However, the
203
258
<link linkend="ini.display-errors">display_errors</link> directive is
204
-
<literal>PHP_INI_ALL</literal> therefore it may be set anywhere,
259
+
<constant>INI_ALL</constant> therefore it may be set anywhere,
205
260
including with <function>ini_set</function>.
206
261
</para>
207
262

208
263
<para>
209
264
<table>
210
-
<title>Definition of PHP_INI_* modes</title>
211
-
<tgroup cols="2">
212
-
<thead>
213
-
<row>
214
-
<entry>Mode</entry>
215
-
<entry>Meaning</entry>
216
-
</row>
217
-
</thead>
218
-
<tbody>
219
-
<row>
220
-
<entry><literal>PHP_INI_USER</literal></entry>
221
-
<entry>
222
-
Entry can be set in user scripts (like with <function>ini_set</function>)
223
-
or in the <link linkend="configuration.changes.windows">Windows registry</link>.
224
-
Since PHP 5.3, entry can be set in &user-ini;
225
-
</entry>
226
-
</row>
227
-
<row>
228
-
<entry><literal>PHP_INI_PERDIR</literal></entry>
229
-
<entry>
230
-
Entry can be set in &php.ini;, &htaccess;, &httpd.conf; or &user-ini;
231
-
(since PHP 5.3)
232
-
</entry>
233
-
</row>
234
-
<row>
235
-
<entry><literal>PHP_INI_SYSTEM</literal></entry>
236
-
<entry>Entry can be set in &php.ini; or &httpd.conf;</entry>
237
-
</row>
238
-
<row>
239
-
<entry><literal>PHP_INI_ALL</literal></entry>
240
-
<entry>Entry can be set anywhere</entry>
241
-
</row>
242
-
</tbody>
243
-
</tgroup>
265
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/></xi:include>
244
266
</table>
245
267
</para>
246
268
</sect1>
...
...
@@ -261,8 +283,8 @@ include_path = ".;c:\php\lib"
261
283
There are several Apache directives that allow you
262
284
to change the PHP configuration from within the Apache configuration
263
285
files. For a listing of which directives are
264
-
<constant>PHP_INI_ALL</constant>, <constant>PHP_INI_PERDIR</constant>,
265
-
or <constant>PHP_INI_SYSTEM</constant>, have a look at the
286
+
<constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>,
287
+
or <constant>INI_SYSTEM</constant>, have a look at the
266
288
<link linkend="ini.list">List of php.ini directives</link> appendix.
267
289
</para>
268
290

...
...
@@ -277,7 +299,7 @@ include_path = ".;c:\php\lib"
277
299
<listitem>
278
300
<para>
279
301
Sets the value of the specified directive.
280
-
Can be used only with <constant>PHP_INI_ALL</constant> and <constant>PHP_INI_PERDIR</constant> type directives.
302
+
Can be used only with <constant>INI_ALL</constant> and <constant>INI_PERDIR</constant> type directives.
281
303
To clear a previously set value use <literal>none</literal> as the value.
282
304
</para>
283
305
<note>
...
...
@@ -297,8 +319,8 @@ include_path = ".;c:\php\lib"
297
319
<listitem>
298
320
<para>
299
321
Used to set a boolean configuration directive.
300
-
Can be used only with <constant>PHP_INI_ALL</constant> and
301
-
<constant>PHP_INI_PERDIR</constant> type directives.
322
+
Can be used only with <constant>INI_ALL</constant> and
323
+
<constant>INI_PERDIR</constant> type directives.
302
324
</para>
303
325
</listitem>
304
326
</varlistentry>
...
...
@@ -381,8 +403,9 @@ include_path = ".;c:\php\lib"
381
403
should have the name of the PHP configuration directive and the
382
404
string value. PHP constants in the values are not parsed.
383
405
However, only configuration values changeable in
384
-
<constant>PHP_INI_USER</constant> can be set
385
-
this way, <constant>PHP_INI_PERDIR</constant> values can not.
406
+
<constant>INI_USER</constant> can be set
407
+
this way, <constant>INI_PERDIR</constant> values can not,
408
+
because these configuration values are re-read for each request.
386
409
</simpara>
387
410
</sect2>
388
411

389
412