<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
 <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 following registry locations are searched in
       order:
       <literal>HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z\IniFilePath</literal>,
       <literal>HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y\IniFilePath</literal> and
       <literal>HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x\IniFilePath</literal>, where
       x, y and z mean the PHP major, minor and release versions.
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath</literal>
       (Windows Registry location)
      </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.cvs.phpini;">the latest &php.ini;</link> from CVS
    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.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;.
         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;.
        </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:"../../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
-->