Skip to content

docs(ini): Clarify php.ini search order and additional .ini scan path in configuration docs #21503

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

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

docs(ini): Clarify php.ini search order and additional .ini scan path in configuration docs #21503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad2904a
docs(ini): clarify ini file search/loading approach [php.ini-production]
joshtrichards Mar 23, 2026
e3a0b2f
docs(ini): clarify ini file search/loading approach [php.ini-developm…
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
34 changes: 21 additions & 13 deletions php.ini-development
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,27 @@
;;;;;;;;;;;;;;;;;;;
; About php.ini ;
;;;;;;;;;;;;;;;;;;;
; PHP's initialization file, generally called php.ini, is responsible for
; configuring many of the aspects of PHP's behavior.

; PHP attempts to find and load this configuration from a number of locations.
; The following is a summary of its search order:
; 1. SAPI module specific location.
; 2. The PHPRC environment variable.
; 3. A number of predefined registry keys on Windows
; 4. Current working directory (except CLI)
; 5. The web server's directory (for SAPI modules), or directory of PHP
; (otherwise in Windows)
; 6. The directory from the --with-config-file-path compile time option, or the
; Windows directory (usually C:\windows)
; PHP's primary initialization file, generally called php.ini, is responsible
; for configuring most aspects of PHP's behavior.
;
; PHP locates this file as follows:
; 1. If the active SAPI provides a php.ini path override, that is used.
Copy link
Member

@iluuu1994 iluuu1994 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is a bit more complicated. The ini override path is used both as a file name and path. Meaning, if a full file is specified, that file is used (e.g. for php-cgi -c /full/path/php.ini). However, a directory can also be specified, in which case PHP will still look for a php-{sapi}.ini and php.ini file in that directory.

; 2. Otherwise, PHP builds a search path from:
; - the PHPRC environment variable,
; - on Windows, the path configured in the registry,
; - 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 (usually C:\windows).
; 3. PHP then looks for php-SAPI.ini in that search path, and if that is not
; found, for php.ini.
;
; 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
; --with-config-file-scan-dir compile-time option.
;
; See the PHP docs for more specific information.
; https://php.net/configuration.file

Expand Down
34 changes: 21 additions & 13 deletions php.ini-production
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,27 @@
;;;;;;;;;;;;;;;;;;;
; About php.ini ;
;;;;;;;;;;;;;;;;;;;
; PHP's initialization file, generally called php.ini, is responsible for
; configuring many of the aspects of PHP's behavior.

; PHP attempts to find and load this configuration from a number of locations.
; The following is a summary of its search order:
; 1. SAPI module specific location.
; 2. The PHPRC environment variable.
; 3. A number of predefined registry keys on Windows
; 4. Current working directory (except CLI)
; 5. The web server's directory (for SAPI modules), or directory of PHP
; (otherwise in Windows)
; 6. The directory from the --with-config-file-path compile time option, or the
; Windows directory (usually C:\windows)
; PHP's primary initialization file, generally called php.ini, is responsible
; for configuring most aspects of PHP's behavior.
;
; PHP locates this file as follows:
; 1. If the active SAPI provides a php.ini path override, that is used.
; 2. Otherwise, PHP builds a search path from:
; - the PHPRC environment variable,
; - on Windows, the path configured in the registry,
; - 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 (usually C:\windows).
; 3. PHP then looks for php-SAPI.ini in that search path, and if that is not
; found, for php.ini.
;
; 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
; --with-config-file-scan-dir compile-time option.
;
; See the PHP docs for more specific information.
; https://php.net/configuration.file

Expand Down
Loading