<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The configuration file</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="configuration.html">Runtime Configuration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="configuration.file.per-user.html">.user.ini files</a></div>
<div class="up"><a href="configuration.html">Runtime Configuration</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="configuration.file" class="sect1">
<h2 class="title">The configuration file</h2>
<p class="simpara">
The configuration file (<var class="filename">php.ini</var>)
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 title="Common Gateway Interface">CGI</acronym> and <acronym title="Command Line Interpreter/Interface">CLI</acronym> versions, it happens on
every invocation.
</p>
<p class="para">
<var class="filename">php.ini</var> is searched for in these locations (in order):
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
SAPI module specific location (<em>PHPIniDir</em> directive
in Apache 2, <em>-c</em> command line option in CGI and CLI,
<em>php_ini</em> parameter in NSAPI,
<em>PHP_INI_PATH</em> environment variable in THTTPD)
</span>
</li>
<li class="listitem">
<span class="simpara">
The <var class="varname"><var class="varname">PHPRC</var></var> environment variable. Before PHP 5.2.0,
this was checked after the registry key mentioned below.
</span>
</li>
<li class="listitem">
<span class="simpara">
As of PHP 5.2.0, the location of the <em>php.ini</em> 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 <em>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</em> for 32-bit version of PHP on a 64-bit OS use <em>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</em>] instead.
For same bitness installation the following registry keys
are examined in order:
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</em>,
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</em> and
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</em>, 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:
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</em>,
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</em> and
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</em>, where
x, y and z mean the PHP major, minor and release versions.
If there is a
value for <em>IniFilePath</em> in any of these keys, the first
one found will be used as the location of the <em>php.ini</em>
(Windows only).
</span>
</li>
<li class="listitem">
<span class="simpara">
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</em> or
<em>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</em>, value of
<em>IniFilePath</em> (Windows only).
</span>
</li>
<li class="listitem">
<span class="simpara">
Current working directory (except CLI).
</span>
</li>
<li class="listitem">
<span class="simpara">
The web server's directory (for SAPI modules), or directory of PHP
(otherwise in Windows).
</span>
</li>
<li class="listitem">
<span class="simpara">
Windows directory (<var class="filename">C:\windows</var>
or <var class="filename">C:\winnt</var>) (for Windows), or
<em>--with-config-file-path</em> compile time option.
</span>
</li>
</ul>
</p>
<p class="para">
If <var class="filename">php-SAPI.ini</var> exists (where SAPI is the SAPI in use,
so, for example, <var class="filename">php-cli.ini</var> or
<var class="filename">php-apache.ini</var>), it is used instead of <var class="filename">php.ini</var>.
The SAPI name can be determined with <span class="function"><a href="function.php-sapi-name.html" class="function">php_sapi_name()</a></span>.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
The Apache web server changes the directory to root at startup, causing
PHP to attempt to read <var class="filename">php.ini</var> from the root filesystem if it exists.
</p>
</p></blockquote>
<p class="para">
Using environment variables can be used in <var class="filename">php.ini</var> as shown below.
</p>
<p class="para">
<div class="example" id="example-36">
<p><strong>Example #1 <var class="filename">php.ini</var> Environment Variables</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">; PHP_MEMORY_LIMIT is taken from environment
memory_limit = ${PHP_MEMORY_LIMIT}</pre>
</div>
</div>
</div>
</p>
<p class="para">
The <var class="filename">php.ini</var> directives handled by extensions are documented
on the respective pages of the extensions themselves. A <a href="ini.html" class="link">list of
the core directives</a> 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
<var class="filename">php.ini</var> file. Alternatively, you may find
<a href="http://git.php.net/?p=php-src.git;a=blob;f=php.ini-production;hb=HEAD" class="link external">» the latest <var class="filename">php.ini</var></a> from Git
helpful too.
</p>
<p class="para">
<div class="example" id="example-37">
<p><strong>Example #2 <var class="filename">php.ini</var> example</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">; 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"</pre>
</div>
</div>
</div>
</p>
<p class="para">
Since PHP 5.1.0, it is possible to refer to existing .ini variables from
within .ini files. Example: <em>open_basedir = ${open_basedir}
":/new/dir"</em>.
</p>
<div class="sect2" id="configuration.file.scan">
<h3 class="title">Scan directories</h3>
<p class="para">
It is possible to configure PHP to scan for .ini files in a directory
after reading <var class="filename">php.ini</var>. This can be done at compile time by setting the
<strong class="option configure">--with-config-file-scan-dir</strong>
option. In
PHP 5.2.0 and later, the scan directory can then be overridden at run time
by setting the <var class="varname"><var class="varname">PHP_INI_SCAN_DIR</var></var> environment variable.
</p>
<p class="para">
It is possible to scan multiple directories by separating them with the
platform-specific path separator (<em>;</em> on Windows, NetWare
and RISC OS; <em>:</em> on all other platforms; the value PHP is
using is available as the <strong><code>PATH_SEPARATOR</code></strong> constant).
If a blank directory is given in <var class="varname"><var class="varname">PHP_INI_SCAN_DIR</var></var>, PHP
will also scan the directory given at compile time via
<strong class="option configure">--with-config-file-scan-dir</strong>
.
</p>
<p class="para">
Within each directory, PHP will scan all files ending in
<em>.ini</em> in alphabetical order. A list of the files that
were loaded, and in what order, is available by calling
<span class="function"><a href="function.php-ini-scanned-files.html" class="function">php_ini_scanned_files()</a></span>, or by running PHP with the
<strong class="option unknown">--ini</strong>
option.
</p>
<div class="informalexample">
<div class="example-contents screen">
<div class="cdata"><pre>
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.
</pre></div>
</div>
</div>
</div>
<div class="sect2" id="configuration.file.changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>7.0.0</td>
<td>
Hash marks (<em>#</em>) are no longer recognized as comments.
</td>
</tr>
<tr>
<td>5.3.0</td>
<td>
Hash marks (<em>#</em>) should no longer be used as comments
and will throw a deprecation warning if used.
</td>
</tr>
<tr>
<td>5.2.0</td>
<td>
The <var class="varname"><var class="varname">PHP_INI_SCAN_DIR</var></var> environment variable can be
set to override the scan directory set via the configure script.
</td>
</tr>
<tr>
<td>5.1.0</td>
<td>
It is possible to refer to existing .ini variables from within .ini files.
</td>
</tr>
</tbody>
</table>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="configuration.html">Runtime Configuration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="configuration.file.per-user.html">.user.ini files</a></div>
<div class="up"><a href="configuration.html">Runtime Configuration</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
