From 38b40da33081c444044535accf2dcfdf114c4412 Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 23 Mar 2026 10:26:11 -0400 Subject: [PATCH 1/2] docs: Clarify configuration file search order --- install/ini.xml | 188 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 128 insertions(+), 60 deletions(-) diff --git a/install/ini.xml b/install/ini.xml index 0fbf03a05951..f75e27509080 100644 --- a/install/ini.xml +++ b/install/ini.xml @@ -6,81 +6,76 @@ The configuration file - - 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 - CGI and CLI versions, it happens on - every invocation. - - &php.ini; is searched for in these locations (in order): - - - - SAPI module specific location (PHPIniDir directive - in Apache 2, -c command line option in CGI and CLI) - - - - - The PHPRC environment variable. - - - - - The location of the php.ini 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 [(HKEY_LOCAL_MACHINE\SOFTWARE\PHP] for 32-bit version of PHP on a 64-bit OS use [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]] instead. - For same bitness installation the following registry keys - are examined in order: - [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z], - [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] and - [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], 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: - [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z], - [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y] and - [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x], where - x, y and z mean the PHP major, minor and release versions. - If there is a - value for IniFilePath in any of these keys, the first - one found will be used as the location of the php.ini - (Windows only). - - - - - [HKEY_LOCAL_MACHINE\SOFTWARE\PHP] or - [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP], value of - IniFilePath (Windows only). - - + 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 CGI and + CLI versions, it happens on every invocation. + + + PHP locates the primary configuration file as follows: + - Current working directory (except CLI). + If the active SAPI provides a specific &php.ini; path override, that + is used (for example, the PHPIniDir directive in + Apache 2, or the -c command line option in + CGI and CLI). - 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: + + + + The PHPRC environment variable. + + + + + On Windows, the path configured in the registry + (IniFilePath). + + + + + The current working directory, except for SAPIs that disable this, + such as CLI. + + + + + The directory of the PHP executable or SAPI module. + + + + + The directory specified by the + --with-config-file-path compile time option, or + the Windows directory (C:\windows + or C:\winnt) on Windows. + + + - Windows directory (C:\windows - or C:\winnt) (for Windows), or - --with-config-file-path compile time option. + PHP then looks for php-SAPI.ini in that search + path, and if that is not found, for &php.ini;. The SAPI name can be + determined with php_sapi_name. - + - If php-SAPI.ini exists (where SAPI is the SAPI in use, - so, for example, php-cli.ini or - php-apache.ini), it is used instead of &php.ini;. - The SAPI name can be determined with php_sapi_name. + After the primary configuration file step, PHP may additionally scan for + .ini files in the path specified by the + PHP_INI_SCAN_DIR environment variable, or, if that is + not set, by the + compile time + option. @@ -88,6 +83,79 @@ PHP to attempt to read &php.ini; from the root filesystem if it exists. + + Windows registry location + + + On Windows, PHP may obtain the location of the primary configuration + file from the registry using the IniFilePath value. + + + + The exact registry keys examined depend on the PHP version and whether + PHP and Windows are 32-bit or 64-bit. + + + + 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: + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\PHP] + + + + In these keys, x, y, and + z refer to the PHP major, minor, and release + versions. If any of these keys contains an + IniFilePath value, the first one found is used. + + + + For 32-bit PHP on a 64-bit OS, the following registry keys are + examined in order: + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x.y.z] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x.y] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP\x] + + + + + [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP] + + + + If any of these keys contains an IniFilePath value, + the first one found is used. + + Environment variables can be referenced within configuration values in &php.ini; as shown below. As of PHP 8.3.0, a fallback value can From 39ca97ebc842449dcce2bcb8bb6c9e170e8a8a10 Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 23 Mar 2026 11:04:04 -0400 Subject: [PATCH 2/2] config file: Clarify php.ini search order ...and restructure Windows registry details --- install/ini.xml | 90 ++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/install/ini.xml b/install/ini.xml index f75e27509080..d63bd9e64928 100644 --- a/install/ini.xml +++ b/install/ini.xml @@ -44,6 +44,12 @@ The current working directory, except for SAPIs that disable this, such as CLI. + + + 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. + + @@ -77,12 +83,6 @@ compile time option. - - - 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. - - Windows registry location @@ -121,12 +121,13 @@ + + In these keys, x, y, and z refer to the PHP major, minor, and release versions. If any of these keys contains an IniFilePath value, the first one found is used. - - + For 32-bit PHP on a 64-bit OS, the following registry keys are examined in order: @@ -152,41 +153,45 @@ + + If any of these keys contains an IniFilePath value, the first one found is used. - + - - 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. - - - &php.ini; Environment Variables - + + Configuration file syntax + + 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. + + + &php.ini; Environment Variables + - - - - The &php.ini; directives handled by extensions are documented - on the respective pages of the extensions themselves. A list of - the core directives 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 - the latest &php.ini; from Git - helpful too. - - - - &php.ini; example - + + + + The &php.ini; directives handled by extensions are documented + on the respective pages of the extensions themselves. A list of + the core directives 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 + the latest &php.ini; from Git + helpful too. + + + + &php.ini; example + - + - - - - It is possible to refer to existing .ini variables from - within .ini files. Example: open_basedir = ${open_basedir} - ":/new/dir". - + + + + It is possible to refer to existing .ini variables from + within .ini files. Example: open_basedir = ${open_basedir} + ":/new/dir". + + Scan directories