Runtime Configuration

The configuration file

The configuration file (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.

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).
• Current working directory (except CLI).
• The web server's directory (for SAPI modules), or directory of PHP (otherwise in Windows).
• Windows directory (C:\windows or C:\winnt) (for Windows), or --with-config-file-path compile time option.

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 Ini. The SAPI name can be determined with php_sapi_name().

Environment variables can be referenced within configuration values in 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.

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 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 Ini file. Alternatively, you may find the latest Ini from Git helpful too.

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 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.

.user.ini files

PHP includes support for configuration INI files on a per-directory basis. These files are processed only by the CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner extension. If you are running PHP as Apache module, use Htaccess files for the same effect.

In addition to the main Ini file, PHP scans for INI files in each directory, starting with the directory of the requested PHP file, and working its way up to the current document root (as set in $_SERVER['DOCUMENT_ROOT']). In case the PHP file is outside the document root, only its directory is scanned.

Only INI settings with the modes INI_ALL, INI_PERDIR and INI_USER will be recognized in .user.ini-style INI files.

Two new INI directives, user_ini.filename and user_ini.cache_ttl control the use of user INI files.

user_ini.filename sets the name of the file PHP looks for in each directory; if set to an empty string, PHP doesn't scan at all. The default is .user.ini.

user_ini.cache_ttl controls how often user INI files are re-read. The default is 300 seconds (5 minutes).

Where a configuration setting may be set

These modes determine when and where a PHP directive may or may not be set, and each directive within the manual refers to one of these modes. For example, some settings may be set within a PHP script using ini_set(), whereas others may require Ini or Conf.

For example, the output_buffering setting is INI_PERDIR therefore it may not be set using ini_set(). However, the display_errors directive is INI_ALL therefore it may be set anywhere, including with ini_set().

INI_USER (int)

Entry can be set in user scripts (like with ini_set()) or in the Windows registry. Entry can be set in User-ini

INI_PERDIR (int)

Entry can be set in Ini, Htaccess, Conf or User-ini

INI_SYSTEM (int)

Entry can be set in Ini or Conf

INI_ALL (int)

Entry can be set anywhere

How to change configuration settings

Running PHP as an Apache module

When using PHP as an Apache module, you can also change the configuration settings using directives in Apache configuration files (e.g. Conf) and Htaccess files. You will need "AllowOverride Options" or "AllowOverride All" privileges to do so.

There are several Apache directives that allow you to change the PHP configuration from within the Apache configuration files. For a listing of which directives are INI_ALL, INI_PERDIR, or INI_SYSTEM, have a look at the List of php.ini directives appendix.

php_valuenamevalue

Sets the value of the specified directive. Can be used only with INI_ALL and INI_PERDIR type directives. To clear a previously set value use none as the value.

Note

Don't use php_value to set boolean values. php_flag (see below) should be used instead.

php_flagnameon|off

Used to set a boolean configuration directive. Can be used only with INI_ALL and INI_PERDIR type directives.

php_admin_valuenamevalue

Sets the value of the specified directive. This can not be used in Htaccess files. Any directive type set with php_admin_value can not be overridden by Htaccess or ini_set(). To clear a previously set value use none as the value.

php_admin_flagnameon|off

Used to set a boolean configuration directive. This can not be used in Htaccess files. Any directive type set with php_admin_flag can not be overridden by Htaccess or ini_set().

Apache configuration example

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>

Changing PHP configuration via the Windows registry

When running PHP on Windows, the configuration values can be modified on a per-directory basis using the Windows registry. The configuration values are stored in the registry key HKLM\SOFTWARE\PHP\Per Directory Values, in the sub-keys corresponding to the path names. For example, configuration values for the directory c:\inetpub\wwwroot would be stored in the key HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot. The settings for the directory would be active for any script running from this directory or any subdirectory of it. The values under the key should have the name of the PHP configuration directive and the string value. PHP constants in the values are not parsed. However, only configuration values changeable in INI_USER can be set this way, INI_PERDIR values can not, because these configuration values are re-read for each request.

Other interfaces to PHP

Regardless of how you run PHP, you can change certain values at runtime of your scripts through ini_set(). See the documentation on the ini_set() page for more information.

If you are interested in a complete list of configuration settings on your system with their current values, you can execute the phpinfo() function, and review the resulting page. You can also access the values of individual configuration directives at runtime using ini_get() or get_cfg_var().