[doc-en] master: Clarify php.ini search order and restructure Windows registry details (#5438)

Author: Josh (joshtrichards) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-19T10:19:51+02:00 Commit: https://github.com/php/doc-en/commit/42b47025176b4d1d6ac6b6ba8d46b317b8206baa Raw diff: https://github.com/php/doc-en/commit/42b47025176b4d1d6ac6b6ba8d46b317b8206baa.diff Clarify php.ini search order and restructure Windows registry details (#5438) * docs: Clarify configuration file search order * config file: Clarify php.ini search order ...and restructure Windows registry details * Use simpara for inline-only paragraphs and unwrap example from para --------- Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M install/ini.xml Diff: diff --git a/install/ini.xml b/install/ini.xml index c0c1ca610c73..1d0df072a523 100644 --- a/install/ini.xml +++ b/install/ini.xml @@ -7,115 +7,187 @@ <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. + 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. </simpara> <para> - &php.ini; is searched for in these locations (in order): - <itemizedlist> + PHP locates the primary configuration file as follows: + <orderedlist> <listitem> <simpara> - SAPI module specific location (<literal>PHPIniDir</literal> directive - in Apache 2, <literal>-c</literal> command line option in CGI and 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 <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 a 32-bit version of PHP on a 64-bit OS use <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal> instead. - For a 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). + 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> + <simpara> + 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. + </simpara> + </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> - </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>. + </orderedlist> </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> <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. + 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. </simpara> - <example> - <title>&php.ini; Environment Variables</title> - <programlisting role="ini"> + <sect2 xml:id="configuration.file.windows"> + <title>Windows registry location</title> + + <simpara> + On Windows, PHP may obtain the location of the primary configuration + file from the registry using the <literal>IniFilePath</literal> value. + </simpara> + + <simpara> + The exact registry keys examined depend on the PHP version and whether + PHP and Windows are 32-bit or 64-bit. + </simpara> + + <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> + </programlisting> + </example> + <simpara> + 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. + </simpara> <example> <title>&php.ini; example</title> <programlisting role="ini"> @@ -135,14 +207,14 @@ include_path = ".:/usr/local/lib/php" include_path = ".;c:\php\lib" ]]> </programlisting> - <!-- TODO: add more details about values and expressions --> + <!-- 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> + <simpara> + It is possible to refer to existing .ini variables from + within .ini files. Example: <literal>open_basedir = ${open_basedir} + ":/new/dir"</literal>. + </simpara> + </sect2> <sect2 xml:id="configuration.file.scan"> <title>Scan directories</title>