PHP Manual: The configuration file

The configuration file

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:

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).
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.
  
  Note:
  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.
- 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.
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().

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.

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.

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.

Example #1 php.ini Environment Variables

; 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}

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.

Example #2 php.ini example

; any text on a line after an unquoted semicolon (;) is ignored
[php] ; section markers (text within square brackets) are also ignored
; Boolean values can be set to either:
;    true, on, yes
; or false, off, no, none
register_globals = off
track_errors = yes

; you can enclose strings in double-quotes
include_path = ".:/usr/local/lib/php"

; backslashes are treated the same as any other character
include_path = ".;c:\php\lib"

It is possible to refer to existing .ini variables from within .ini files. Example: open_basedir = ${open_basedir} ":/new/dir".

Scan directories

It is possible to configure PHP to scan for .ini files in a directory after reading php.ini. This can be done at compile time by setting the --with-config-file-scan-dir option. The scan directory can then be overridden at run time by setting the PHP_INI_SCAN_DIR environment variable.

It is possible to scan multiple directories by separating them with the platform-specific path separator (; on Windows, NetWare and RISC OS; : on all other platforms; the value PHP is using is available as the PATH_SEPARATOR constant). If a blank directory is given in PHP_INI_SCAN_DIR, PHP will also scan the directory given at compile time via --with-config-file-scan-dir.

Within each directory, PHP will scan all files ending in .ini in alphabetical order. A list of the files that were loaded, and in what order, is available by calling php_ini_scanned_files(), or by running PHP with the --ini option.

Assuming PHP is configured with --with-config-file-scan-dir=/etc/php.d,
and that the path separator is :...

$ php
  PHP will load all files in /etc/php.d/*.ini as configuration files.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP will load all files in /usr/local/etc/php.d/*.ini as
  configuration files.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP will load all files in /etc/php.d/*.ini, then
  /usr/local/etc/php.d/*.ini as configuration files.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP will load all files in /usr/local/etc/php.d/*.ini, then
  /etc/php.d/*.ini as configuration files.