install/ini.xml
9ab074d32484672f93e5d822f42fb94ae9088207
...
...
@@ -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>
...
...
@@ -82,20 +88,23 @@
82
88
PHP to attempt to read &php.ini; from the root filesystem if it exists.
83
89
</para>
84
90
</note>
85
-
<para>
86
-
Using environment variables can be used in &php.ini; as shown below.
87
-
</para>
88
-
<para>
89
-
<example>
90
-
<title>&php.ini; Environment Variables</title>
91
-
<programlisting role="ini">
91
+
<simpara>
92
+
Environment variables can be referenced within configuration values
93
+
in &php.ini; as shown below. As of PHP 8.3.0, a fallback value can
94
+
be specified that will be used when the referenced variable is not
95
+
defined.
96
+
</simpara>
97
+
<example>
98
+
<title>&php.ini; Environment Variables</title>
99
+
<programlisting role="ini">
92
100
<![CDATA[
93
101
; PHP_MEMORY_LIMIT is taken from environment
94
102
memory_limit = ${PHP_MEMORY_LIMIT}
103
+
; If PHP_MAX_EXECUTION_TIME is not defined, it will fall back to 30
104
+
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
95
105
]]>
96
-
</programlisting>
97
-
</example>
98
-
</para>
106
+
</programlisting>
107
+
</example>
99
108
<para>
100
109
The &php.ini; directives handled by extensions are documented
101
110
on the respective pages of the extensions themselves. A <link linkend="ini">list of
...
...
@@ -130,20 +139,73 @@ include_path = ".;c:\php\lib"
130
139
</example>
131
140
</para>
132
141
<para>
133
-
Since PHP 5.1.0, it is possible to refer to existing .ini variables from
142
+
It is possible to refer to existing .ini variables from
134
143
within .ini files. Example: <literal>open_basedir = ${open_basedir}
135
144
":/new/dir"</literal>.
136
145
</para>
146
+
<sect2 xml:id="configuration.file.scan">
147
+
<title>Scan directories</title>
148
+

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

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

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

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

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

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

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

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

139
201
<sect1 xml:id="configuration.file.per-user">
140
202
<title>.user.ini files</title>
141
203

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

...
...
@@ -156,30 +218,26 @@ include_path = ".;c:\php\lib"
156
218
</simpara>
157
219
<simpara>
158
220
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
221
+
modes <constant>INI_PERDIR</constant> and
222
+
<constant>INI_USER</constant> will be recognized in .user.ini-style INI
161
223
files.
162
224
</simpara>
163
225

164
226
<simpara>
165
227
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
-
-->
228
+
<link linkend="ini.user-ini.filename">user_ini.filename</link> and
229
+
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
172
230
control the use of user INI files.
173
231
</simpara>
174
232

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

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

208
266
<para>
209
-
<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>
244
-
</table>
267
+
<variablelist>
268
+
<!--
269
+
Replace everything inside the <variablelist> element with an <xi:include>
270
+
once libxml2 gets XInclude 1.1 attribute copying support.
271
+
The below <xi:include> will include the appropriate elements
272
+
but needs all top-level xml:id's removed (see XInclude 1.1 set-xml-id).
273
+

274
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/></xi:include>
275
+
-->
276
+
<title>INI mode constants</title>
277
+
<varlistentry>
278
+
<term>
279
+
<constant>INI_USER</constant>
280
+
(<type>int</type>)
281
+
</term>
282
+
<listitem>
283
+
<simpara>
284
+
Entry can be set in user scripts (like with <function xmlns="http://docbook.org/ns/docbook">ini_set</function>)
285
+
or in the <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">Windows registry</link>.
286
+
Entry can be set in &user-ini;
287
+
</simpara>
288
+
</listitem>
289
+
</varlistentry>
290
+
<varlistentry>
291
+
<term>
292
+
<constant>INI_PERDIR</constant>
293
+
(<type>int</type>)
294
+
</term>
295
+
<listitem>
296
+
<simpara>
297
+
Entry can be set in &php.ini;, &htaccess;, &httpd.conf; or &user-ini;
298
+
</simpara>
299
+
</listitem>
300
+
</varlistentry>
301
+
<varlistentry>
302
+
<term>
303
+
<constant>INI_SYSTEM</constant>
304
+
(<type>int</type>)
305
+
</term>
306
+
<listitem>
307
+
<simpara>
308
+
Entry can be set in &php.ini; or &httpd.conf;
309
+
</simpara>
310
+
</listitem>
311
+
</varlistentry>
312
+
<varlistentry>
313
+
<term>
314
+
<constant>INI_ALL</constant>
315
+
(<type>int</type>)
316
+
</term>
317
+
<listitem>
318
+
<simpara>
319
+
Entry can be set anywhere
320
+
</simpara>
321
+
</listitem>
322
+
</varlistentry>
323
+
</variablelist>
245
324
</para>
246
325
</sect1>
247
326

...
...
@@ -261,8 +340,8 @@ include_path = ".;c:\php\lib"
261
340
There are several Apache directives that allow you
262
341
to change the PHP configuration from within the Apache configuration
263
342
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
343
+
<constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>,
344
+
or <constant>INI_SYSTEM</constant>, have a look at the
266
345
<link linkend="ini.list">List of php.ini directives</link> appendix.
267
346
</para>
268
347

...
...
@@ -277,7 +356,7 @@ include_path = ".;c:\php\lib"
277
356
<listitem>
278
357
<para>
279
358
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.
359
+
Can be used only with <constant>INI_ALL</constant> and <constant>INI_PERDIR</constant> type directives.
281
360
To clear a previously set value use <literal>none</literal> as the value.
282
361
</para>
283
362
<note>
...
...
@@ -297,8 +376,8 @@ include_path = ".;c:\php\lib"
297
376
<listitem>
298
377
<para>
299
378
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.
379
+
Can be used only with <constant>INI_ALL</constant> and
380
+
<constant>INI_PERDIR</constant> type directives.
302
381
</para>
303
382
</listitem>
304
383
</varlistentry>
...
...
@@ -381,8 +460,9 @@ include_path = ".;c:\php\lib"
381
460
should have the name of the PHP configuration directive and the
382
461
string value. PHP constants in the values are not parsed.
383
462
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.
463
+
<constant>INI_USER</constant> can be set
464
+
this way, <constant>INI_PERDIR</constant> values can not,
465
+
because these configuration values are re-read for each request.
386
466
</simpara>
387
467
</sect2>
388
468

389
469



Translation status