mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
8335b04e9e
Update regarding implemented feature request #67331 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@345643 c90b9560-bf6c-de11-be94-00142212c4b1
530 lines
19 KiB
XML
530 lines
19 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Runtime Configuration</title>
|
|
|
|
<sect1 xml:id="configuration.file">
|
|
<title>The configuration file</title>
|
|
|
|
<simpara>
|
|
The configuration file (&php.ini;)
|
|
is read when PHP starts up. For the server module versions of PHP,
|
|
this happens only once when the web server is started. For the
|
|
<acronym>CGI</acronym> and <acronym>CLI</acronym> versions, it happens on
|
|
every invocation.
|
|
</simpara>
|
|
<para>
|
|
&php.ini; is searched for in these locations (in order):
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
SAPI module specific location (<literal>PHPIniDir</literal> directive
|
|
in Apache 2, <literal>-c</literal> command line option in CGI and CLI,
|
|
<literal>php_ini</literal> parameter in NSAPI,
|
|
<literal>PHP_INI_PATH</literal> environment variable in THTTPD)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
The <varname>PHPRC</varname> environment variable. Before PHP 5.2.0,
|
|
this was checked after the registry key mentioned below.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
As of PHP 5.2.0, the location of the <literal>php.ini</literal> file
|
|
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.
|
|
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.
|
|
For same bitness installation the following registry keys
|
|
are examined in order:
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> and
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, where
|
|
x, y and z mean the PHP major, minor and release versions.
|
|
For 32 bit versions of PHP on a 64 bit OS the following registry keys are examined in order:
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> and
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, where
|
|
x, y and z mean the PHP major, minor and release versions.
|
|
If there is a
|
|
value for <literal>IniFilePath</literal> in any of these keys, the first
|
|
one found will be used as the location of the <literal>php.ini</literal>
|
|
(Windows only).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> or
|
|
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, value of
|
|
<literal>IniFilePath</literal> (Windows only).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Current working directory (except CLI).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
The web server's directory (for SAPI modules), or directory of PHP
|
|
(otherwise in Windows).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Windows directory (<filename class="directory">C:\windows</filename>
|
|
or <filename class="directory">C:\winnt</filename>) (for Windows), or
|
|
<literal>--with-config-file-path</literal> compile time option.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
If <filename>php-SAPI.ini</filename> exists (where SAPI is the SAPI in use,
|
|
so, for example, <filename>php-cli.ini</filename> or
|
|
<filename>php-apache.ini</filename>), it is used instead of &php.ini;.
|
|
The SAPI name can be determined with <function>php_sapi_name</function>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The Apache web server changes the directory to root at startup, causing
|
|
PHP to attempt to read &php.ini; from the root filesystem if it exists.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Using environment variables can be used in &php.ini; as shown below.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>&php.ini; Environment Variables</title>
|
|
<programlisting role="ini">
|
|
<![CDATA[
|
|
; PHP_MEMORY_LIMIT is taken from environment
|
|
memory_limit = ${PHP_MEMORY_LIMIT}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The &php.ini; directives handled by extensions are documented
|
|
on the respective pages of the extensions themselves. A <link linkend="ini">list of
|
|
the core directives</link> is available in the appendix. Not all
|
|
PHP directives are necessarily documented in this manual: for a complete list
|
|
of directives available in your PHP version, please read your well commented
|
|
&php.ini; file. Alternatively, you may find
|
|
<link xlink:href="&url.php.git.phpini;">the latest &php.ini;</link> from Git
|
|
helpful too.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>&php.ini; example</title>
|
|
<programlisting role="ini">
|
|
<![CDATA[
|
|
; any text on a line after an unquoted semicolon (;) is ignored
|
|
[php] ; section markers (text within square brackets) are also ignored
|
|
; Boolean values can be set to either:
|
|
; true, on, yes
|
|
; or false, off, no, none
|
|
register_globals = off
|
|
track_errors = yes
|
|
|
|
; you can enclose strings in double-quotes
|
|
include_path = ".:/usr/local/lib/php"
|
|
|
|
; backslashes are treated the same as any other character
|
|
include_path = ".;c:\php\lib"
|
|
]]>
|
|
</programlisting>
|
|
<!-- TODO: add more details about values and expressions -->
|
|
</example>
|
|
</para>
|
|
<para>
|
|
Since PHP 5.1.0, it is possible to refer to existing .ini variables from
|
|
within .ini files. Example: <literal>open_basedir = ${open_basedir}
|
|
":/new/dir"</literal>.
|
|
</para>
|
|
<sect2 xml:id="configuration.file.scan">
|
|
<title>Scan directories</title>
|
|
|
|
<para>
|
|
It is possible to configure PHP to scan for .ini files in a directory
|
|
after reading &php.ini;. This can be done at compile time by setting the
|
|
<option role="configure">--with-config-file-scan-dir</option> option. In
|
|
PHP 5.2.0 and later, the scan directory can then be overridden at run time
|
|
by setting the <varname>PHP_INI_SCAN_DIR</varname> environment variable.
|
|
</para>
|
|
|
|
<para>
|
|
It is possible to scan multiple directories by separating them with the
|
|
platform-specific path separator (<literal>;</literal> on Windows, NetWare
|
|
and RISC OS; <literal>:</literal> on all other platforms; the value PHP is
|
|
using is available as the <constant>PATH_SEPARATOR</constant> constant).
|
|
If a blank directory is given in <varname>PHP_INI_SCAN_DIR</varname>, PHP
|
|
will also scan the directory given at compile time via
|
|
<option role="configure">--with-config-file-scan-dir</option>.
|
|
</para>
|
|
|
|
<para>
|
|
Within each directory, PHP will scan all files ending in
|
|
<literal>.ini</literal> in alphabetical order. A list of the files that
|
|
were loaded, and in what order, is available by calling
|
|
<function>php_ini_scanned_files</function>, or by running PHP with the
|
|
<option>--ini</option> option.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
Assuming PHP is configured with --with-config-file-scan-dir=/etc/php.d,
|
|
and that the path separator is :...
|
|
|
|
$ php
|
|
PHP will load all files in /etc/php.d/*.ini as configuration files.
|
|
|
|
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
|
|
PHP will load all files in /usr/local/etc/php.d/*.ini as
|
|
configuration files.
|
|
|
|
$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
|
|
PHP will load all files in /etc/php.d/*.ini, then
|
|
/usr/local/etc/php.d/*.ini as configuration files.
|
|
|
|
$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
|
|
PHP will load all files in /usr/local/etc/php.d/*.ini, then
|
|
/etc/php.d/*.ini as configuration files.
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</sect2>
|
|
<sect2 xml:id="configuration.file.changelog">
|
|
&reftitle.changelog;
|
|
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>7.0.0</entry>
|
|
<entry>
|
|
Hash marks (<literal>#</literal>) are no longer recognized as comments.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.3.0</entry>
|
|
<entry>
|
|
Hash marks (<literal>#</literal>) should no longer be used as comments
|
|
and will throw a deprecation warning if used.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.2.0</entry>
|
|
<entry>
|
|
The <varname>PHP_INI_SCAN_DIR</varname> environment variable can be
|
|
set to override the scan directory set via the configure script.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.1.0</entry>
|
|
<entry>
|
|
It is possible to refer to existing .ini variables from within .ini files.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="configuration.file.per-user">
|
|
<title>.user.ini files</title>
|
|
|
|
<simpara>
|
|
Since PHP 5.3.0, PHP includes support for configuration INI files on a
|
|
per-directory basis. These files are processed <emphasis>only</emphasis> by
|
|
the CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner
|
|
extension. If you are running PHP as Apache module, use &htaccess; files for the same
|
|
effect.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
In addition to the main &php.ini; file, PHP scans for INI files in each
|
|
directory, starting with the directory of the requested PHP file, and
|
|
working its way up to the current document root (as set in
|
|
<varname>$_SERVER['DOCUMENT_ROOT']</varname>). In case the PHP file is
|
|
outside the document root, only its directory is scanned.
|
|
</simpara>
|
|
<simpara>
|
|
Only INI settings with the
|
|
modes <constant>PHP_INI_PERDIR</constant> and
|
|
<constant>PHP_INI_USER</constant> will be recognized in .user.ini-style INI
|
|
files.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
Two new INI directives,
|
|
<link linkend="ini.user-ini.filename">user_ini.filename</link> and
|
|
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
|
|
control the use of user INI files.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
<link linkend="ini.user-ini.filename">user_ini.filename</link> sets the name of the file PHP looks for
|
|
in each directory; if set to an empty string, PHP doesn't scan at all. The
|
|
default is <literal>.user.ini</literal>.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
<link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> controls how often user INI files are
|
|
re-read. The default is 300 seconds (5 minutes).
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="configuration.changes.modes">
|
|
<title>Where a configuration setting may be set</title>
|
|
|
|
<para>
|
|
These modes determine when and where a PHP directive may or may not
|
|
be set, and each directive within the manual refers to one of these
|
|
modes. For example, some settings may be set within a PHP script
|
|
using <function>ini_set</function>, whereas others may require
|
|
&php.ini; or &httpd.conf;.
|
|
</para>
|
|
|
|
<para>
|
|
For example, the
|
|
<link linkend="ini.output-buffering">output_buffering</link> setting
|
|
is <literal>PHP_INI_PERDIR</literal> therefore it may not be set using
|
|
<function>ini_set</function>. However, the
|
|
<link linkend="ini.display-errors">display_errors</link> directive is
|
|
<literal>PHP_INI_ALL</literal> therefore it may be set anywhere,
|
|
including with <function>ini_set</function>.
|
|
</para>
|
|
|
|
<para>
|
|
<table>
|
|
<title>Definition of PHP_INI_* modes</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Mode</entry>
|
|
<entry>Meaning</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>PHP_INI_USER</literal></entry>
|
|
<entry>
|
|
Entry can be set in user scripts (like with <function>ini_set</function>)
|
|
or in the <link linkend="configuration.changes.windows">Windows registry</link>.
|
|
Since PHP 5.3, entry can be set in &user-ini;
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>PHP_INI_PERDIR</literal></entry>
|
|
<entry>
|
|
Entry can be set in &php.ini;, &htaccess;, &httpd.conf; or &user-ini;
|
|
(since PHP 5.3)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>PHP_INI_SYSTEM</literal></entry>
|
|
<entry>Entry can be set in &php.ini; or &httpd.conf;</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>PHP_INI_ALL</literal></entry>
|
|
<entry>Entry can be set anywhere</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="configuration.changes">
|
|
<title>How to change configuration settings</title>
|
|
|
|
<sect2 xml:id="configuration.changes.apache">
|
|
<title>Running PHP as an Apache module</title>
|
|
<simpara>
|
|
When using PHP as an Apache module, you can also change the
|
|
configuration settings using directives in Apache configuration
|
|
files (e.g. &httpd.conf;) and &htaccess; files. You will need
|
|
"AllowOverride Options" or "AllowOverride All" privileges to do so.
|
|
</simpara>
|
|
|
|
<para>
|
|
There are several Apache directives that allow you
|
|
to change the PHP configuration from within the Apache configuration
|
|
files. For a listing of which directives are
|
|
<constant>PHP_INI_ALL</constant>, <constant>PHP_INI_PERDIR</constant>,
|
|
or <constant>PHP_INI_SYSTEM</constant>, have a look at the
|
|
<link linkend="ini.list">List of php.ini directives</link> appendix.
|
|
</para>
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<systemitem role="directive">php_value</systemitem>
|
|
<parameter>name</parameter>
|
|
<parameter>value</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the value of the specified directive.
|
|
Can be used only with <constant>PHP_INI_ALL</constant> and <constant>PHP_INI_PERDIR</constant> type directives.
|
|
To clear a previously set value use <literal>none</literal> as the value.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
Don't use <systemitem role="directive">php_value</systemitem> to set boolean values.
|
|
<systemitem role="directive">php_flag</systemitem> (see below) should be used instead.
|
|
</simpara>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<systemitem role="directive">php_flag</systemitem>
|
|
<parameter>name</parameter>
|
|
<parameter>on|off</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Used to set a boolean configuration directive.
|
|
Can be used only with <constant>PHP_INI_ALL</constant> and
|
|
<constant>PHP_INI_PERDIR</constant> type directives.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<systemitem role="directive">php_admin_value</systemitem>
|
|
<parameter>name</parameter>
|
|
<parameter>value</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the value of the specified directive.
|
|
This <emphasis>can not be used</emphasis> in &htaccess; files.
|
|
Any directive type set with <systemitem role="directive">php_admin_value</systemitem>
|
|
can not be overridden by &htaccess; or <function>ini_set</function>.
|
|
To clear a previously set value use <literal>none</literal> as the value.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<systemitem role="directive">php_admin_flag</systemitem>
|
|
<parameter>name</parameter>
|
|
<parameter>on|off</parameter>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Used to set a boolean configuration directive.
|
|
This <emphasis>can not be used</emphasis> in &htaccess; files.
|
|
Any directive type set with <systemitem role="directive">php_admin_flag</systemitem>
|
|
can not be overridden by &htaccess; or <function>ini_set</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Apache configuration example</title>
|
|
<programlisting role="ini">
|
|
<![CDATA[
|
|
<IfModule mod_php5.c>
|
|
php_value include_path ".:/usr/local/lib/php"
|
|
php_admin_flag engine on
|
|
</IfModule>
|
|
<IfModule mod_php4.c>
|
|
php_value include_path ".:/usr/local/lib/php"
|
|
php_admin_flag engine on
|
|
</IfModule>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<caution>
|
|
<para>
|
|
PHP constants do not exist outside of PHP. For example, in
|
|
&httpd.conf; you can not use PHP constants
|
|
such as <constant>E_ALL</constant> or <constant>E_NOTICE</constant>
|
|
to set the <link linkend="ini.error-reporting">error_reporting</link>
|
|
directive as they will have no meaning and will evaluate to
|
|
<emphasis>0</emphasis>. Use the associated bitmask values instead.
|
|
These constants can be used in &php.ini;
|
|
</para>
|
|
</caution>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="configuration.changes.windows">
|
|
<title>Changing PHP configuration via the Windows registry</title>
|
|
<simpara>
|
|
When running PHP on Windows, the configuration values can be
|
|
modified on a per-directory basis using the Windows registry. The
|
|
configuration values are stored in the registry key
|
|
<literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
|
|
in the sub-keys corresponding to the path names. For example, configuration
|
|
values for the directory <literal>c:\inetpub\wwwroot</literal> would
|
|
be stored in the key <literal>HKLM\SOFTWARE\PHP\Per Directory
|
|
Values\c\inetpub\wwwroot</literal>. The settings for the
|
|
directory would be active for any script running from this
|
|
directory or any subdirectory of it. The values under the key
|
|
should have the name of the PHP configuration directive and the
|
|
string value. PHP constants in the values are not parsed.
|
|
However, only configuration values changeable in
|
|
<constant>PHP_INI_USER</constant> can be set
|
|
this way, <constant>PHP_INI_PERDIR</constant> values can not.
|
|
</simpara>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="configuration.changes.other">
|
|
<title>Other interfaces to PHP</title>
|
|
<para>
|
|
Regardless of how you run PHP, you can change certain values at runtime
|
|
of your scripts through <function>ini_set</function>. See the documentation
|
|
on the <function>ini_set</function> page for more information.
|
|
</para>
|
|
<para>
|
|
If you are interested in a complete list of configuration settings
|
|
on your system with their current values, you can execute the
|
|
<function>phpinfo</function> function, and review the resulting
|
|
page. You can also access the values of individual configuration
|
|
directives at runtime using <function>ini_get</function> or
|
|
<function>get_cfg_var</function>.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|