Skip to content

Clarify php.ini search order and restructure Windows registry details #5438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joshtrichards wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Clarify php.ini search order and restructure Windows registry details #5438

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
38b40da
docs: Clarify configuration file search order
joshtrichards Mar 23, 2026
39ca97e
config file: Clarify php.ini search order
joshtrichards Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 171 additions & 97 deletions install/ini.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,119 +6,192 @@
<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)
</simpara>
</listitem>
<listitem>
<simpara>
The <varname>PHPRC</varname> environment variable.
</simpara>
</listitem>
<listitem>
<simpara>
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>
The primary 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.
</para>
<para>
PHP locates the primary configuration file as follows:
<orderedlist>
<listitem>
<simpara>
Current working directory (except CLI).
If the active SAPI provides a specific &php.ini; path override, that
is used (for example, the <literal>PHPIniDir</literal> directive in
Apache 2, or the <literal>-c</literal> command line option in
<acronym>CGI</acronym> and <acronym>CLI</acronym>).
</simpara>
</listitem>
<listitem>
<simpara>
The web server's directory (for SAPI modules), or directory of PHP
(otherwise in Windows).
Otherwise, PHP builds a search path from the following locations:
</simpara>
<itemizedlist>
<listitem>
<simpara>
The <varname>PHPRC</varname> environment variable.
</simpara>
</listitem>
<listitem>
<simpara>
On Windows, the path configured in the registry
(<literal>IniFilePath</literal>).
</simpara>
</listitem>
<listitem>
<simpara>
The current working directory, except for SAPIs that disable this,
such as <acronym>CLI</acronym>.
</simpara>
<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>
</listitem>
<listitem>
<simpara>
The directory of the PHP executable or SAPI module.
</simpara>
</listitem>
<listitem>
<simpara>
The directory specified by the
<literal>--with-config-file-path</literal> compile time option, or
the Windows directory (<filename class="directory">C:\windows</filename>
or <filename class="directory">C:\winnt</filename>) on Windows.
</simpara>
</listitem>
</itemizedlist>
</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.
PHP then looks for <filename>php-SAPI.ini</filename> in that search
path, and if that is not found, for &php.ini;. The SAPI name can be
determined with <function>php_sapi_name</function>.
</simpara>
</listitem>
</itemizedlist>
</orderedlist>
</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>.
After the primary configuration file step, PHP may additionally scan for
<literal>.ini</literal> files in the path specified by the
<varname>PHP_INI_SCAN_DIR</varname> environment variable, or, if that is
not set, by the
<option role="configure">--with-config-file-scan-dir</option> compile time
option.
</para>
<note>
<sect2 xml:id="configuration.file.windows">
<title>Windows registry location</title>

<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.
On Windows, PHP may obtain the location of the primary configuration
file from the registry using the <literal>IniFilePath</literal> value.
</para>
</note>
<simpara>
Environment variables can be referenced within configuration values
in &php.ini; as shown below. As of PHP 8.3.0, a fallback value can
be specified that will be used when the referenced variable is not
defined.
</simpara>
<example>
<title>&php.ini; Environment Variables</title>
<programlisting role="ini">

<para>
The exact registry keys examined depend on the PHP version and whether
PHP and Windows are 32-bit or 64-bit.
</para>

<para>
For 32-bit PHP on a 32-bit OS, or 64-bit PHP on a 64-bit OS, the
following registry keys are examined in order:
<itemizedlist>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
In these keys, <literal>x</literal>, <literal>y</literal>, and
<literal>z</literal> refer to the PHP major, minor, and release
versions. If any of these keys contains an
<literal>IniFilePath</literal> value, the first one found is used.
</simpara>
<para>
For 32-bit PHP on a 64-bit OS, the following registry keys are
examined in order:
<itemizedlist>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x.y.z]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x.y]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x]</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
If any of these keys contains an <literal>IniFilePath</literal> value,
the first one found is used.
</simpara>
</sect2>
<sect2 xml:id="configuration.file.syntax">
<title>Configuration file syntax</title>
<simpara>
Environment variables can be referenced within configuration values
in &php.ini; as shown below. As of PHP 8.3.0, a fallback value can
be specified that will be used when the referenced variable is not
defined.
</simpara>
<example>
<title>&php.ini; Environment Variables</title>
<programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT is taken from environment
memory_limit = ${PHP_MEMORY_LIMIT}
; If PHP_MAX_EXECUTION_TIME is not defined, it will fall back to 30
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
]]>
</programlisting>
</example>
<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">
</programlisting>
</example>
<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
Expand All @@ -134,15 +207,16 @@ include_path = ".:/usr/local/lib/php"
; backslashes are treated the same as any other character
include_path = ".;c:\php\lib"
]]>
</programlisting>
</programlisting>
<!-- TODO: add more details about values and expressions -->
</example>
</para>
<para>
It is possible to refer to existing .ini variables from
within .ini files. Example: <literal>open_basedir = ${open_basedir}
":/new/dir"</literal>.
</para>
</example>
</para>
<para>
It is possible to refer to existing .ini variables from
within .ini files. Example: <literal>open_basedir = ${open_basedir}
":/new/dir"</literal>.
</para>
</sect2>
<sect2 xml:id="configuration.file.scan">
<title>Scan directories</title>

Expand Down