<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 331904 $ -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Runtime Configuration</title>
 
 <sect1 xml:id="configuration.file">
  <title>The configuration file</title>
  
  <simpara>
   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
   <acronym>CGI</acronym> and <acronym>CLI</acronym> versions, it happens on
   every invocation.
  </simpara>
  <para>
   &php.ini; is searched for in these locations (in order):
   <itemizedlist>
    <listitem>
     <simpara>
      SAPI module specific location (<literal>PHPIniDir</literal> directive
      in Apache 2, <literal>-c</literal> command line option in CGI and CLI,
      <literal>php_ini</literal> parameter in NSAPI,
      <literal>PHP_INI_PATH</literal> environment variable in THTTPD)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The <varname>PHPRC</varname> environment variable. Before PHP 5.2.0,
      this was checked after the registry key mentioned below.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      As of PHP 5.2.0, the location of the <literal>php.ini</literal> file
      can be set for different versions of PHP. The following registry keys
      are examined in order:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> and
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, where
      x, y and z mean the PHP major, minor and release versions. If there is a
      value for <literal>IniFilePath</literal> in any of these keys, the first
      one found will be used as the location of the <literal>php.ini</literal>
      (Windows only).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>, value of
      <literal>IniFilePath</literal> (Windows only).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Current working directory (except CLI).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The web server's directory (for SAPI modules), or directory of PHP
      (otherwise in Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Windows directory (<filename class="directory">C:\windows</filename>
      or <filename class="directory">C:\winnt</filename>) (for Windows), or
      <literal>--with-config-file-path</literal> compile time option.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   If <filename>php-SAPI.ini</filename> exists (where SAPI is the SAPI in use,
   so, for example, <filename>php-cli.ini</filename> or
   <filename>php-apache.ini</filename>), it is used instead of &php.ini;.
   The SAPI name can be determined with <function>php_sapi_name</function>.
  </para>
  <note>
   <para>
    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.
   </para>
  </note>
  <para>
   Using environment variables can be used in &php.ini; as shown below.
  </para>
  <para>
   <example>
    <title>&php.ini; Environment Variables</title>
     <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT is taken from environment
memory_limit = ${PHP_MEMORY_LIMIT}
]]>
     </programlisting>
    </example>
  </para>
  <para>
   The &php.ini; directives handled by extensions are documented
   on the respective pages of the extensions themselves. A <link linkend="ini">list of
   the core directives</link> 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
   <link xlink:href="&url.php.git.phpini;">the latest &php.ini;</link> from Git
   helpful too.
  </para>
  <para>
   <example>
    <title>&php.ini; example</title>
    <programlisting role="ini">
<![CDATA[
; 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"
]]>
    </programlisting>
    <!-- TODO: add more details about values and expressions -->
   </example>
  </para>
  <para>
   Since PHP 5.1.0, it is possible to refer to existing .ini variables from
   within .ini files. Example: <literal>open_basedir = ${open_basedir}
   ":/new/dir"</literal>.
  </para>
 </sect1>
 
 <sect1 xml:id="configuration.file.per-user">
  <title>.user.ini files</title>
  
  <simpara>
   Since PHP 5.3.0, PHP includes support for configuration INI files on a
   per-directory basis. These files are processed <emphasis>only</emphasis> by
   the CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner
   extension. If you are using Apache, use &htaccess; files for the same
   effect.
  </simpara>
  
  <simpara>
   In addition to the main &php.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
   <varname>$_SERVER['DOCUMENT_ROOT']</varname>). In case the PHP file is
   outside the document root, only its directory is scanned.
  </simpara>
  <simpara>
   Only INI settings with the
   modes <constant>PHP_INI_PERDIR</constant> and
   <constant>PHP_INI_USER</constant> will be recognized in .user.ini-style INI
   files.
  </simpara>
  
  <simpara>
   Two new INI directives,
   <literal>user_ini.filename</literal> and
   <literal>user_ini.cache_ttl</literal>
   <!--
       <link linkend="ini.user-ini.filename">user_ini.filename</link> and
       <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
   -->
   control the use of user INI files.
  </simpara>
  
  <simpara>
   <literal>user_ini.filename</literal> 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 <literal>.user.ini</literal>.
  </simpara>
  
  <simpara>
   <literal>user_ini.cache_ttl</literal> controls how often user INI files are
   re-read. The default is 300 seconds (5 minutes).
  </simpara>
 </sect1>
 
 <sect1 xml:id="configuration.changes.modes">
  <title>Where a configuration setting may be set</title>
  
  <para>
   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 <function>ini_set</function>, whereas others may require
   &php.ini; or &httpd.conf;.
  </para>
  
  <para>
   For example, the
   <link linkend="ini.output-buffering">output_buffering</link> setting
   is <literal>PHP_INI_PERDIR</literal> therefore it may not be set using
   <function>ini_set</function>. However, the
   <link linkend="ini.display-errors">display_errors</link> directive is
   <literal>PHP_INI_ALL</literal> therefore it may be set anywhere,
   including with <function>ini_set</function>.
  </para>
  
  <para>
   <table>
    <title>Definition of PHP_INI_* modes</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Mode</entry>
       <entry>Meaning</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>PHP_INI_USER</literal></entry>
       <entry>
        Entry can be set in user scripts (like with <function>ini_set</function>)
        or in the <link linkend="configuration.changes.windows">Windows registry</link>.
        Since PHP 5.3, entry can be set in &user-ini;
       </entry>
      </row>
      <row>
       <entry><literal>PHP_INI_PERDIR</literal></entry>
       <entry>
        Entry can be set in &php.ini;, &htaccess;, &httpd.conf; or &user-ini;
        (since PHP 5.3)
       </entry>
      </row>
      <row>
       <entry><literal>PHP_INI_SYSTEM</literal></entry>
       <entry>Entry can be set in &php.ini; or &httpd.conf;</entry>
      </row>
      <row>
       <entry><literal>PHP_INI_ALL</literal></entry>
       <entry>Entry can be set anywhere</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>
 
 <sect1 xml:id="configuration.changes">
  <title>How to change configuration settings</title>
  
  <sect2 xml:id="configuration.changes.apache">
   <title>Running PHP as an Apache module</title>
   <simpara>
    When using PHP as an Apache module, you can also change the
    configuration settings using directives in Apache configuration
    files (e.g. &httpd.conf;) and &htaccess; files. You will need
    "AllowOverride Options" or "AllowOverride All" privileges to do so.
   </simpara>
   
   <para>
    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
    <constant>PHP_INI_ALL</constant>, <constant>PHP_INI_PERDIR</constant>,
    or <constant>PHP_INI_SYSTEM</constant>, have a look at the
    <link linkend="ini.list">List of php.ini directives</link> appendix.
   </para>
   
   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Sets the value of the specified directive.
        Can be used only with <constant>PHP_INI_ALL</constant> and <constant>PHP_INI_PERDIR</constant> type directives.
        To clear a previously set value use <literal>none</literal> as the value.
       </para>
       <note>
        <simpara>
         Don't use <systemitem role="directive">php_value</systemitem> to set boolean values.
         <systemitem role="directive">php_flag</systemitem> (see below) should be used instead.
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Used to set a boolean configuration directive.
        Can be used only with <constant>PHP_INI_ALL</constant> and
        <constant>PHP_INI_PERDIR</constant> type directives.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Sets the value of the specified directive.
        This <emphasis>can not be used</emphasis> in &htaccess; files.
        Any directive type set with <systemitem role="directive">php_admin_value</systemitem>
        can not be overridden by &htaccess; or <function>ini_set</function>.
        To clear a previously set value use <literal>none</literal> as the value.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Used to set a boolean configuration directive.
        This <emphasis>can not be used</emphasis> in &htaccess; files.
        Any directive type set with <systemitem role="directive">php_admin_flag</systemitem>
        can not be overridden by &htaccess; or <function>ini_set</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Apache configuration example</title>
     <programlisting role="ini">
<![CDATA[
<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>
]]>
     </programlisting>
    </example>
   </para>
   <caution>
    <para>
     PHP constants do not exist outside of PHP. For example, in
     &httpd.conf; you can not use PHP constants
     such as <constant>E_ALL</constant> or <constant>E_NOTICE</constant>
     to set the <link linkend="ini.error-reporting">error_reporting</link>
     directive as they will have no meaning and will evaluate to
     <emphasis>0</emphasis>. Use the associated bitmask values instead.
     These constants can be used in &php.ini;
    </para>
   </caution>
  </sect2>
  
  <sect2 xml:id="configuration.changes.windows">
   <title>Changing PHP configuration via the Windows registry</title>
   <simpara>
    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
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
    in the sub-keys corresponding to the path names. For example, configuration
    values for the directory <literal>c:\inetpub\wwwroot</literal> would
    be stored in the key <literal>HKLM\SOFTWARE\PHP\Per Directory
    Values\c\inetpub\wwwroot</literal>. 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
    <constant>PHP_INI_USER</constant> can be set
    this way, <constant>PHP_INI_PERDIR</constant> values can not.
   </simpara>
  </sect2>
  
  <sect2 xml:id="configuration.changes.other">
   <title>Other interfaces to PHP</title>
   <para>
    Regardless of how you run PHP, you can change certain values at runtime
    of your scripts through <function>ini_set</function>. See the documentation
    on the <function>ini_set</function> page for more information.
   </para>
   <para>
    If you are interested in a complete list of configuration settings
    on your system with their current values, you can execute the
    <function>phpinfo</function> function, and review the resulting
    page. You can also access the values of individual configuration
    directives at runtime using <function>ini_get</function> or
    <function>get_cfg_var</function>.
   </para>
  </sect2>
 </sect1>
 
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->