<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
 <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> version, it happens on
    every invocation.
   </simpara>
   <para>
    &php.ini; is searched in these locations (in order):
    <itemizedlist>
     <listitem>
      <para>
       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)
      </para>
     </listitem>
     <listitem>
      <para>
       The <varname>PHPRC</varname> environment variable. Before PHP 5.2.0
       this was checked after the registry key mentioned below.
      </para>
     </listitem>
     <listitem>
      <para>
       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 these keys, then the first
       one found will be used as the location of the <literal>php.ini</literal> (Windows only).
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>, value of
       <literal>IniFilePath</literal> (Windows only).
      </para>
     </listitem>
     <listitem>
      <para>
       Current working directory (except CLI)
      </para>
     </listitem>
     <listitem>
      <para>
       The web server's directory (for SAPI modules), or directory of PHP
       (otherwise in Windows)
      </para>
     </listitem>
     <listitem>
      <para>
       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
      </para>
     </listitem>
    </itemizedlist> 
   </para>
   <para>
    If <filename>php-SAPI.ini</filename> exists (where SAPI is used SAPI, so the
    filename is e.g. <filename>php-cli.ini</filename> or
    <filename>php-apache.ini</filename>), it's used instead of &php.ini;.
    SAPI name can be determined by <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>
    The &php.ini; directives handled by extensions are documented respectively
    on the pages of the extensions themselves. The <link linkend="ini">list of
    the core directives</link> is available in the appendix. Probably not all
    PHP directives are documented in the manual though. For a complete list
    of directives available in your PHP version, please read your well commented
    &php.ini; file. Alternatively, you may find the
    <link xlink:href="&url.php.svn.phpini;">the latest &php.ini;</link> from SVN
    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 .htaccess-style 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>). 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="3">
      <thead>
       <row>
        <entry>Mode</entry>
        <entry>Value</entry>
        <entry>Meaning</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><literal>PHP_INI_USER</literal></entry>
        <entry>1</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>
        </entry>
       </row>
       <row>
        <entry><literal>PHP_INI_PERDIR</literal></entry>
        <entry>6</entry>
        <entry>Entry can be set in &php.ini;, &htaccess; or &httpd.conf;</entry>
       </row>
       <row>
        <entry><literal>PHP_INI_SYSTEM</literal></entry>
        <entry>4</entry>
        <entry>Entry can be set in &php.ini; or &httpd.conf;</entry>
       </row>
       <row>
        <entry><literal>PHP_INI_ALL</literal></entry>
        <entry>7</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 safe_mode on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag safe_mode 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
-->