ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9ab074d32484672f93e5d822f42fb94ae9088207 Maintainer: nikic Status: ready -->
<!-- CREDITS: wiesemann -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>Laufzeiteinstellungen</title>

 <sect1 xml:id="configuration.file">
  <title>Die Konfigurationsdatei</title>

  <simpara>
   Die Konfigurationsdatei (&php.ini;) wird beim Start von PHP eingelesen. Für
   die Servermodul-Versionen von PHP geschieht dies nur einmal beim Start des
   Webservers. Für die <acronym>CGI</acronym>- und
   <acronym>CLI</acronym>-Versionen geschieht dies bei jedem Aufruf.
  </simpara>
  <para>
   Nach der &php.ini; wird an folgenden Orten in der angegebenen Reihenfolge
   gesucht:
   <itemizedlist>
    <listitem>
     <simpara>
      Spezielle Orte für SAPI-Module (<literal>PHPIniDir</literal>-Direktive
      im Apache2, <literal>-c</literal> Kommandozeilenparameter in CGI und
      CLI)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Die <varname>PHPRC</varname>-Umgebungsvariable.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Die Position der <literal>php.ini</literal>-Datei kann für verschiedene
      Versionen von PHP gesetzt werden. Die Wurzel der Registrierungsschlüssel
      hängt davon ab, ob es sich um ein 32- oder 64-bit-System handelt, und
      ebenfalls von der PHP-Version. Für 32-bit-PHP auf einem 32-bit-System
      oder für 64-bit-PHP auf einem 64-bit-System ist
      <literal>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> zu verwenden; für
      32-bit-PHP auf einem 64-bit-System ist stattdessen
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>] zu
      verwenden. Bei einer Installation mit derselben Bitanzahl werden die
      folgenden Registrierungsschlüssel in der angegebenen Reihenfolge
      durchsucht:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> und
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, wobei x, y und z
      die Major-, Minor- und Release-Versionen von PHP darstellen.
      Für 32-bit PHP-Versionen auf einem 64-bit-System werden die folgenden
      Registrierungsschlüssel in der angegebenen Reihenfolge durchsucht:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> und
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, wobei
      x, y und z die Major-, Minor- und Release-Versionen von PHP darstellen.
      Falls ein Wert für <literal>IniFilePath</literal> in einem dieser
      Schlüssel existiert, so wird der zuerst gefundene als Position der
      <literal>php.ini</literal> verwendet (nur unter Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> bzw.
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, Wert von
      <literal>IniFilePath</literal> (nur unter Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Aktuelles Arbeitsverzeichnis (außer CLI).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Das Webserververzeichnis (für SAPI-Module) oder das PHP-Verzeichnis
      (andernfalls in Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Windows-Verzeichnis (<filename class="directory">C:\windows</filename>
      oder <filename class="directory">C:\winnt</filename>) (unter Windows)
      oder die <literal>--with-config-file-path</literal>-Kompilierungsoption.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Falls die Datei <filename>php-SAPI.ini</filename> existiert (wobei SAPI die
   verwendete SAPI ist, was als Dateinamen &zb;
   <filename>php-cli.ini</filename> oder <filename>php-apache.ini</filename>
   ergibt), wird diese anstelle der &php.ini; verwendet. Der Name der SAPI
   kann durch <function>php_sapi_name</function> ermittelt werden.
  </para>
  <note>
   <para>
    Der Apache-Webserver wechselt beim Start das Arbeitsverzeichnis in das
    Wurzelverzeichnis, weshalb PHP versucht, die &php.ini; aus dem
    Wurzelverzeichnis zu lesen, wenn diese existiert.
   </para>
  </note>
  <simpara>
   Umgebungsvariablen können in Konfigurationswerten in der &php.ini;
   referenziert werden, wie unten gezeigt. Seit PHP 8.3.0 kann ein Standardwert
   angegeben werden, der verwendet wird, wenn die referenzierte Variable nicht
   definiert ist.
  </simpara>
  <example>
   <title>&php.ini;-Umgebungsvariablen</title>
   <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT ist der Name einer Umgebungsvariablen
memory_limit = ${PHP_MEMORY_LIMIT}
; Wenn PHP_MAX_EXECUTION_TIME nicht gesetzt ist, wird der Standardwert 30 verwendet
max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}
]]>
   </programlisting>
  </example>
  <para>
   Die Optionen der &php.ini; für Extensions werden auf den Handbuchseiten
   der jeweiligen Extensions behandelt. Die <link linkend="ini">Beschreibung
   der &php.ini;-Direktiven des Sprachkerns</link> ist im Anhang verfügbar. Es werden
   jedoch möglicherweise nicht alle PHP-Direktiven im Handbuch erläutert. Für
   eine komplette Liste der in Ihrer PHP-Version verfügbaren Einstellungen
   lesen Sie bitte die gut kommentierte &php.ini;. Möglicherweise kann die
   <link xlink:href="&url.php.git.phpini;">aktuellste &php.ini;</link> aus dem
   Git-Repository ebenfalls hilfreich sein.
  </para>
  <para>
   <example>
    <title>&php.ini;-Beispiel</title>
    <programlisting role="ini">
<![CDATA[
; Jeder Text in einer Zeile nach einem Semikolon, welches nicht
; in Anführungszeichen steht, wird ignoriert
[php] ; Abschnittsmarkierungen (Text in eckigen Klammern) werden ebenfalls ignoriert
; Boolesche Werte können auf einen der folgenden Werte eingestellt werden:
;      true, on, yes
; oder false, off, no, none
register_globals = off
track_errors = yes

; Sie können Zeichenketten in Anführungszeichen einschließen
include_path = ".:/usr/local/lib/php"

; Backslashes werden wie alle anderen Zeichen behandelt
include_path = ".;c:\php\lib"
]]>
    </programlisting>
    <!-- TODO: add more details about values and expressions -->
   </example>
  </para>
  <para>
   Es ist möglich, sich auf bereits definierte .ini-Variablen innerhalb der
   .ini-Dateien zu beziehen. Zum Beispiel:
   <literal>open_basedir = ${open_basedir}":/new/dir"</literal>.
  </para>
  <sect2 xml:id="configuration.file.scan">
   <title>Scan-Verzeichnisse</title>

   <para>
    Es ist möglich, PHP so zu konfigurieren, dass nach .ini Dateien in einem
    Verzeichnis gesucht wird, nachdem &php.ini; gelesen wurde. Dies kann zur
    Kompilierzeit durch Setzen der Option <option
    role="configure">--with-config-file-scan-dir</option> erfolgen. Das
    Scan-Verzeichnis kann zur Laufzeit überschrieben werden, indem die
    Umgebungsvariable <varname>PHP_INI_SCAN_DIR</varname> gesetzt wird.
   </para>

   <para>
    Es ist möglich, mehrere Verzeichnisse anzugeben, indem sie mit dem
    plattformspezifischen Pfadtrenner (<literal>;</literal> unter Windows,
    NetWare und RISC OS; <literal>:</literal> auf allen anderen Plattformen;
    der Wert, den PHP verwendet, is als <constant>PATH_SEPARATOR</constant>
    verfügbar). Wird in <varname>PHP_INI_SCAN_DIR</varname> ein leeres
    Verzeichnis angegeben, dann wird PHP beim Kompilieren auch das mit
    <option role="configure">--with-config-file-scan-dir</option> angegebene
    Verzeichnis durchsuchen.
   </para>

   <para>
    In jedem Verzeichnis wird PHP alle Dateien mit der Erweiterung
    <literal>.ini</literal> in alphabetischer Reihenfolge lesen. Eine gemäß der
    Reihenfolge geordnete Liste der geladenen Dateien ist durch Aufruf von
    <function>php_ini_scanned_files</function> verfügbar, oder indem PHP mit der
    Option <option>--ini</option> ausgeführt wird.
   </para>

   <informalexample>
    <screen>
<![CDATA[
Wir nehmen an, dass PHP mit --with-config-file-scan-dir=/etc/php.d kompiliert
wurde, und dass der Pfadtrenner : ist...

$ php
  PHP wird alle Dateien in /etc/php.d/*.ini als Konfigurationsdateien laden.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP wird alle Dateien in /usr/local/etc/php.d/*.ini als
  Konfigurationsdateien laden.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP wird alle Dateien in /etc/php.d/*.ini, und dann
  /usr/local/etc/php.d/*.ini als Konfigurationsdateien laden.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP wird alle Dateien in /usr/local/etc/php.d/*.ini, und dann
  /etc/php.d/*.ini als Konfigurationsdateien laden.
]]>
    </screen>
   </informalexample>
  </sect2>
 </sect1>

 <sect1 xml:id="configuration.file.per-user">
  <title>.user.ini-Dateien</title>

  <simpara>
   PHP bietet Unterstützung für Konfigurations-INI-Dateien auf
   Verzeichnisebene an. Diese Dateien werden <emphasis>nur</emphasis> durch
   die CGI/FastCGI-SAPI verarbeitet. Durch diese Funktionalität wird die
   PECL-Erweiterung htscanner obsolet. Falls Sie PHP als Apache-Modul
   ausführen, können Sie für denselben Effekt &htaccess;-Dateien benutzen.
  </simpara>

  <simpara>
   Zusätzlich zur Haupt-&php.ini;-Datei sucht PHP auch nach INI-Dateien
   in jedem Verzeichnis, beginnend mit dem Verzeichnis in der die
   angeforderte PHP-Datei liegt, aufwärts bis hin zum aktuellen "document root"
   (wie in <varname>$_SERVER['DOCUMENT_ROOT']</varname> angezeigt).
   Falls sich die PHP-Datei außerhalb des "document root" befindet, wird
   nur das Verzeichnis, in dem sich die Datei befindet, durchsucht.
  </simpara>
  <simpara>
   Nur INI-Einstellungen mit den Modi <constant>INI_PERDIR</constant>
   und <constant>INI_USER</constant> werden als .user.ini-INI-Dateien
   erkannt.
  </simpara>

  <simpara>
   Zwei neue INI-Direktiven,
   <link linkend="ini.user-ini.filename">user_ini.filename</link> und
   <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
   steuern die Nutzung der Benutzer-INI-Dateien.
  </simpara>

  <simpara>
   <link linkend="ini.user-ini.filename">user_ini.filename</link> setzt den Namen der Datei, die
   von PHP in jedem Verzeichnis gesucht wird; falls dies auf eine leere
   Zeichenkette gesetzt wird, sucht PHP nach keiner Datei. Der Standardwert
   ist <literal>.user.ini</literal>.
  </simpara>

  <simpara>
   <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> steuert, wie oft die
   Benutzer-INI-Dateien neu eingelesen werden. Der Standardwert beträgt
   300 Sekunden (5 Minuten).
  </simpara>
 </sect1>

 <sect1 xml:id="configuration.changes.modes">
  <title>Wo Konfigurationseinstellungen gesetzt werden können</title>

  <para>
   Diese Modi bestimmen wann und wo eine PHP-Direktive gesetzt oder
   nicht gesetzt werden kann. Jede Direktive im Handbuch verweist auf
   einen dieser Modi. Zum Beispiel können einige Einstellungen in
   einem PHP-Skript mittels <function>ini_set</function> gesetzt
   werden, während andere nur über die &php.ini; oder &httpd.conf;
   gesetzt werden können.
  </para>

  <para>
   Ein Beispiel ist die
   <link linkend="ini.output-buffering">output_buffering</link>-Einstellung.
   Wegen <constant>INI_PERDIR</constant> kann sie nicht mittels
   <function>ini_set</function> gesetzt werden. Die
   <link linkend="ini.display-errors">display_errors</link>-Einstellung
   hingegegen kann wegen <constant>INI_ALL</constant> überall
   gesetzt werden, also auch mittels <function>ini_set</function>.
  </para>

  <para>
   <variablelist>
    <title>Konstanten für die INI-Modi</title>
    <varlistentry>
     <term>
      <constant>INI_USER</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Der Eintrag kann in Benutzerskripten gesetzt werden (&zb; mit
       <function xmlns="http://docbook.org/ns/docbook">ini_set</function>)
       oder in der
       <link xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.windows">Windows-Registry</link>.
       Der Eintrag kann in der &user-ini; gesetzt werden
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_PERDIR</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Der Eintrag kann in der &php.ini;, der &htaccess;, der &httpd.conf; oder
       der &user-ini; gesetzt werden
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_SYSTEM</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Der Eintrag kann in der &php.ini; oder der &httpd.conf; gesetzt werden
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <constant>INI_ALL</constant>
      (<type>int</type>)
     </term>
     <listitem>
      <simpara>
       Der Eintrag kann überall gesetzt werden
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

 <sect1 xml:id="configuration.changes">
  <title>Wie man Konfigurationseinstellungen ändert</title>

  <sect2 xml:id="configuration.changes.apache">
   <title>PHP läuft als Apachemodul</title>
   <simpara>
    Wenn man PHP als Apachemodul verwendet, kann man die
    Konfigurationseinstellungen mittels Direktiven in den
    Apache-Konfigurationsdateien (&zb; &httpd.conf;) und &htaccess;-Dateien
    ändern. Dafür benötigt man "AllowOverride Options"- oder
    "AllowOverride All"-Privilegien.
   </simpara>

   <para>
    Es gibt verschiedene Apachedirektiven, die es erlauben,
    die PHP-Konfiguration aus den Apache-Konfigurationsdateien heraus zu
    ändern. Für eine Liste von Direktiven, die als
    <constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>,
    oder <constant>INI_SYSTEM</constant> definiert sind, werfen Sie einen
    Blick auf den Anhang
    <link linkend="ini.list">Liste von php.ini Einstellungen</link>.
   </para>

   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>Name</parameter>
       <parameter>Wert</parameter>
      </term>
      <listitem>
       <para>
        Setzt den Wert der angegebenen Direktive.
        Kann nur für Direktiven mit den Typen <constant>INI_ALL</constant>
        und <constant>INI_PERDIR</constant> verwendet werden. Um einen
        vorher gesetzten Wert zu löschen, verwenden Sie
        <literal>none</literal> als Wert.
       </para>
       <note>
        <simpara>
         Verwenden Sie <systemitem role="directive">php_value</systemitem>
         nicht, um boolesche Werte zu setzen.
         <systemitem role="directive">php_flag</systemitem> (siehe unten)
         sollte stattdessen verwendet werden.
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>Name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Setzt eine boolesche Konfigurationsdirektive.
        Kann nur für Direktiven mit den Typen <constant>INI_ALL</constant>
        und <constant>INI_PERDIR</constant> verwendet werden.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_value</systemitem>
       <parameter>Name</parameter>
       <parameter>Wert</parameter>
      </term>
      <listitem>
       <para>
        Setzt den Wert der angegebenen Direktive.
        Dies kann <emphasis>nicht</emphasis> in &htaccess;-Dateien verwendet
        werden.
        Jeder Direktiventyp, der mit <systemitem role="directive">
        php_admin_value</systemitem> gesetzt wird, kann nicht durch
        &htaccess;-Direktiven oder mit <function>ini_set</function>
        überschrieben werden.
        Um einen vorher gesetzten Wert zu löschen, verwenden Sie
        <literal>none</literal> als Wert.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_flag</systemitem>
       <parameter>Name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Setzt eine boolesche Konfigurationsdirektive.
        Dies kann <emphasis>nicht</emphasis> in &htaccess;-Dateien verwendet
        werden.
        Jeder Direktiventyp, der mit <systemitem role="directive">php_admin_value</systemitem>
        gesetzt wird, kann nicht durch &htaccess;-Direktiven oder
        <function>ini_set</function> überschrieben werden.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Apache-Konfigurationsbeispiel</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-Konstanten existieren nicht außerhalb von PHP. So kann man &zb; in
     der &httpd.conf; nicht PHP-Konstanten wie <constant>E_ALL</constant>
     oder <constant>E_NOTICE</constant> verwenden, um den Wert der
     <link linkend="ini.error-reporting">error_reporting</link>-Direktive
     zu ändern, da diese keine Bedeutung haben und als <emphasis>0</emphasis>
     ausgewertet werden. Verwenden Sie stattdessen die zugehörigen
     Bitmasken-Werte direkt. Diese Konstanten können in der &php.ini;
     verwendet werden.
    </para>
   </caution>
  </sect2>

  <sect2 xml:id="configuration.changes.windows">
   <title>Die PHP-Konfiguration mit der Windows Registry ändern</title>
   <simpara>
    Wenn Sie PHP unter Windows einsetzen, können Sie die
    Konfigurationseinstellungen für jedes einzelne Verzeichnis mit der
    Windows-Registry anpassen. Die Werte der Konfiguration werden unterhalb
    des Registrierungsschlüssels
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal> in den zum
    Verzeichnisnamen passenden Unterschlüssel gespeichert.Zum Beispiel
    würden Werte für das Verzeichnis <literal>c:\inetpub\wwwroot</literal>
    im Registrierungsschlüssel <literal>HKLM\SOFTWARE\PHP\Per Directory
    Values\c\inetpub\wwwroot</literal> gespeichert werden. Die
    Einstellungen für dieses Verzeichnis wären für alle Skripte aktiv,
    die in diesem Verzeichnis oder einem seiner Unterverzeichnisse laufen.
    Die Werte in diesem Schlüssel sollten den Namen eine PHP-
    Konfigurationsdirektive und einen Zeichenkettenwert haben.
    Konstenten in den Werten werden nicht ausgewertet. Es können jedoch
    nur Werte, die in <constant>INI_USER</constant> änderbar sind,
    auf diese Weise gesetzt werden, nicht als
    <constant>INI_PERDIR</constant> deklarierte Werte,
    da diese Konfigurationswerte für jeden Request erneut gelesen werden.
   </simpara>
  </sect2>

  <sect2 xml:id="configuration.changes.other">
   <title>Andere Zugänge zu PHP</title>
   <para>
    Egal wie Sie PHP betreiben, Sie können bestimmte Werte zur Laufzeit
    Ihrer Skripte mittels <function>ini_set</function> setzen. Werfen Sie
    dazu einen Blick auf die Dokumentation von <function>ini_set</function>.
   </para>
   <para>
    Wenn Sie an einer kompletten Liste von Konfigurationseinstellungen Ihres
    Systems inklusive deren aktuellen Werten interessiert sind, können Sie
    die Funktion <function>phpinfo</function> ausführen und die daraus
    resultierende Seite betrachten. Sie können auf die Werte einzelner
    Konfigurationsdirektiven zur Laufzeit mittels
    <function>ini_get</function> oder <function>get_cfg_var</function>
    zugreifen.
   </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
-->