Skip to content

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

Open
joshtrichards wants to merge 2 commits intophp:masterfrom
joshtrichards:jtr/docs-php-ini-loading
Open

docs(ini): Clarify php.ini search order and additional .ini scan path in configuration docs#21503
joshtrichards wants to merge 2 commits intophp:masterfrom
joshtrichards:jtr/docs-php-ini-loading

Conversation

@joshtrichards
Copy link

Improve the php.ini configuration-file documentation to better match the implementation and make the loading process clearer.

This update:

  • clarifies that the documented sequence refers to the primary configuration file,
  • explains the distinction between a SAPI-provided override and the normal search-path construction,
  • makes it clear that PHP looks for php-SAPI.ini before php.ini,
  • and separates primary-file lookup from the later scan for additional .ini files via PHP_INI_SCAN_DIR or --with-config-file-scan-dir.

Same change in both production and development sample ini file.

@joshtrichards joshtrichards marked this pull request as ready for review March 23, 2026 14:05
Copy link
Member

@iluuu1994 iluuu1994 left a comment

Choose a reason for hiding this comment

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

Honestly, I'm not totally convinced this is the right place to document this anyway. INI files are migrated from one PHP version to the next, and this documentation is bound to get outdated.

; 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

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants