parse-ini-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a5346daf2bb2fab250fa03f0f6639a408d0b2240 Maintainer: simp Status: ready -->
<refentry xml:id="function.parse-ini-file" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>parse_ini_file</refname>
  <refpurpose>Parst eine Konfigurationsdatei</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>parse_ini_file</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>process_sections</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>scanner_mode</parameter><initializer><constant>INI_SCANNER_NORMAL</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>parse_ini_file</function> lädt die in
   <parameter>filename</parameter> angegebene Datei, und gibt
   die darin enthaltenen Einstellungen in einem assoziativen
   Array zurück.
  </para>
  <para>
   Die Struktur der Ini-Datei ist identisch zur &php.ini;.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Der Dateiname der zu parsenden ini-Datei. Wenn ein relativer Pfad
       verwendet wird, wird er relativ zum aktuellen Arbeitsverzeichnis
       ausgewertet und dann entsprechend dem
       <link linkend="ini.include-path">include_path</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>process_sections</parameter></term>
     <listitem>
      <para>
       Setzt man den Parameter <parameter>process_sections</parameter>
       auf &true;, erhält man ein mehrdimensionales Array mit den
       Gruppennamen und Einstellungen. Der Standardwert für
       <parameter>process_sections</parameter> ist &false;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>scanner_mode</parameter></term>
     <listitem>
      <para>
       Kann entweder <constant>INI_SCANNER_NORMAL</constant> (Standard) oder
       <constant>INI_SCANNER_RAW</constant> sein. Ist
       <constant>INI_SCANNER_RAW</constant> gesetzt, so werden die Werte der
       Optionen nicht geparst.
      </para>
      &ini.scanner.typed;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Im Erfolgsfall werden die Einstellungen als assoziatives <type>Array</type>
   zurückgegeben, ansonsten &false;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Inhalt der <filename>sample.ini</filename></title>
    <programlisting>
<![CDATA[
; Dies ist ein Beispiel für eine Konfigurationsdatei
; Kommentare beginnen wie in der php.ini mit ';'

[erste_gruppe]
eins = 1
fünf = 5
tier = VOGEL

[zweite_gruppe]
pfad = /usr/local/bin
URL = "http://www.example.com/~username"

[dritte_gruppe]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"
]]>
    </programlisting>
   </example>
   <example>
    <title><function>parse_ini_file</function>-Beispiel</title>
    <para>
     Abgesehen von "magischen Konstanten" wie <constant>__FILE__</constant>
     können auch <link linkend="language.constants">Konstanten</link> in einer
     Ini-Datei geparst werden, indem man einen INI-Wert als Konstante
     definiert, bevor <function>parse_ini_file</function> aufgerufen wird.
     Diese Konstante wird in die Ergebnisse integriert. Dabei werden nur
     INI-Werte ausgewertet und der Wert muss genau die Konstante sein. Zum
     Beispiel:
    </para>
    <programlisting role="php">
<![CDATA[
<?php

define ('VOGEL', 'Amsel');

// Ohne Gruppen analysieren
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// Mit Gruppen analysieren
$ini_array = parse_ini_file("sample.ini", TRUE);
print_r($ini_array);

?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [eins] => 1
    [fünf] => 5
    [tier] => Amsel
    [pfad] => /usr/local/bin
    [URL] => http://www.example.com/~username
    [phpversion] => Array
        (
            [0] => 5.0
            [1] => 5.1
            [2] => 5.2
            [3] => 5.3
        )

    [urls] => Array
        (
            [svn] => http://svn.php.net
            [git] => http://git.php.net
        )

)
Array
(
    [erste_gruppe] => Array
        (
            [eins] => 1
            [fünf] => 5
            [tier] => Amsel
        )

    [zweite_gruppe] => Array
        (
            [pfad] => /usr/local/bin
            [URL] => http://www.example.com/~username
        )

    [dritte_gruppe] => Array
        (
            [phpversion] => Array
                (
                    [0] => 5.0
                    [1] => 5.1
                    [2] => 5.2
                    [3] => 5.3
                )

            [urls] => Array
                (
                    [svn] => http://svn.php.net
                    [git] => http://git.php.net
                )

        )

)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>parse_ini_file</function> parst eine php.ini</title>
    <programlisting role="php">
<![CDATA[
<?php
// Eine einfache Funktion, um das Ergebnis zu vergleichen
function janein($expression)
{
    return($expression ? 'Ja' : 'Nein');
}

// Pfad der php.ini mittels der Funktion php_ini_loaded_file() holen
$ini_path = php_ini_loaded_file();

// Parsen der php.ini
$ini = parse_ini_file($ini_path);

// Werte ausgeben und vergleichen. Beachten Sie dass die Verwendung von
// get_cfg_var() die gleichen Ergebnisse für geparste und geladene
// Werte geben wird
echo '(geparst) magic_quotes_gpc = ' . janein($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(geladen) magic_quotes_gpc = ' . janein(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
(geparst) magic_quotes_gpc = Ja
(geladen) magic_quotes_gpc = Nein
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Wert-Interpolation</title>
    <para>
     Neben der Auswertung von Konstanten haben bestimmte Zeichen eine
     besondere Bedeutung in einem ini-Wert. Darüber hinaus können
     Umgebungsvariablen und zuvor definierte Konfigurationsoptionen (siehe
     <function>get_cfg_var</function>) mit der <code>${}</code>-Syntax gelesen
     werden.
    </para>
    <programlisting>
<![CDATA[
; | wird für bitweises OR verwendet
three = 2|3

; & wird für bitweises AND verwendet
four = 6&5

; ^ wird für bitweises XOR verwendet
five = 3^6

; ~ wird für bitweises Negieren verwendet
negative_two = ~1

; () wird für die Gruppierung verwendet
seven = (8|7)&(6|5)

; Auswerten der Umgebungsvariablen PATH
path = ${PATH}

; Auswerten der Konfigurationsoption "memory_limit".
configured_memory_limit = ${memory_limit}

]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Zeichen maskieren</title>
    <para>
     Einige Zeichen haben in Zeichenketten in doppelten Anführungszeichen eine
     besondere Bedeutung und müssen durch das Backslash-Präfix maskiert
     werden. Dies sind vor allem das doppelte Anführungszeichen <code>"</code>
     als Begrenzungszeichen und der Backslash <code>\</code> selbst (wenn
     darauf ein Sonderzeichen folgt):
    </para>
    <programlisting>
<![CDATA[
quoted = "She said \"Exactly my point\"." ; Ergibt eine Zeichenkette mit Anführungszeichen darin.
hint = "Use \\\" to escape double quote" ; Ergibt: Use \" to escape double quote
]]>
    </programlisting>
    <para>
     Es gibt eine Ausnahme für Windows-ähnliche Pfade: Es ist möglich, den
     abschließenden Backslash nicht zu maskieren, wenn auf die Zeichenkette in
     Anführungsstrichen direkt ein Zeilenumbruch folgt:
    </para>
    <programlisting>
<![CDATA[
save_path = "C:\Temp\"
]]>
    </programlisting>
    <para>
     Wenn man doppelte Anführungszeichen gefolgt von einem Zeilenumbruch in
     einem mehrzeiligen Wert vermeiden muss, ist es möglich, die Verkettung
     von Werten auf folgende Weise zu verwenden (eine Zeichenkette mit zwei
     direkt aufeinanderfolgenden Anführungszeichen):
    </para>
    <programlisting>
<![CDATA[
long_text = "Lorem \"ipsum\"""
 dolor" ; Ergibt: Lorem "ipsum"\n dolor
]]>
    </programlisting>
    <para>
     Ein weiteres Zeichen mit besonderer Bedeutung ist <code>$</code> (das
     Dollarzeichen). Wenn darauf eine öffnende geschweifte Klammer folgt, muss
     es maskiert werden:
    </para>
    <programlisting>
<![CDATA[
code = "\${test}"
]]>
    </programlisting>
    <para>
     Das Maskieren von Zeichen wird im Modus
     <constant>INI_SCANNER_RAW</constant> nicht unterstützt (in diesem Modus
     werden alle Zeichen verarbeitet wie sie sind).
    </para>
    <para>
     Zu beachten ist, dass der ini-Parser keine Standard-Maskierungssequenzen
     unterstützt (<code>\n</code>, <code>\t</code> etc.). Falls erforderlich,
     muss das Ergebnis von <function>parse_ini_file</function> mit der
     Funktion <function>stripcslashes</function> nachbearbeitet werden.
    </para>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Diese Funktion hat nichts mit dem Laden der &php.ini;-Datei zu tun. Diese
    ist zum Ausführungszeitpunkt Ihres Skriptes bereits vollständig
    verarbeitet. Diese Funktion kann verwendet werden, um die
    Konfigurationsdateien Ihrer eigenen Anwendung zu lesen.
   </para>
  </note>
  <note>
   <para>
    Falls ein Wert der Ini-Datei ein nicht alphanumerisches Zeichen enthält
    muss dieser Wert in doppelte Anführungszeichen (") eingeschlossen werden.
   </para>
  </note>
  <note>
   <simpara>
    Es gibt reservierte Schlüsselwörter, welche nicht als Schlüssel in
    Ini-Dateien verwendet werden dürfen. Diese umfassen:
    <literal>null</literal>, <literal>yes</literal>, <literal>no</literal>,
    <literal>true</literal>, <literal>false</literal>, <literal>on</literal>,
    <literal>off</literal>, <literal>none</literal>. Die Werte
    <literal>null</literal>, <literal>off</literal>, <literal>no</literal> und
    <literal>false</literal> ergeben <literal>""</literal> und die Werte
    <literal>on</literal>, <literal>yes</literal> and <literal>true</literal>
    ergeben <literal>"1"</literal>, solange der Modus
    <constant>INI_SCANNER_TYPED</constant> nicht verwendet wird . Die Zeichen
    <literal>?{}|&amp;~!()^"</literal> dürfen in einem Schlüssel nicht
    verwendet werden und haben im Wert besondere Bedeutung.
   </simpara>
  </note>
  <note>
   <para>
    Einträge ohne Gleichheitszeichen werden ignoriert. Beispielsweise würde
    "foo" ignoriert werden, während "bar =" geparst und mit einem leeren Wert
    hinzugefügt würde. Beispielsweise hat MySQL eine Einstellung
    "no-auto-rehash" in der <filename>my.cnf</filename> welche keinen Wert
    enthält und somit ignoriert würde.
   </para>
  </note>
  <note>
   <para>
    Ini-Dateien werden von Webservern in der Regel als reiner Text behandelt
    und daher den Browsern auf Anfrage zur Verfügung gestellt. Das bedeutet,
    dass Sie aus Sicherheitsgründen entweder Ihre ini-Dateien außerhalb des
    Web-Wurzelverzeichnisses (DocRoot) aufbewahren müssen oder Ihren Webserver
    so umkonfigurieren, dass sie nicht ausgeliefert werden. Wenn Sie beides
    nicht tun, kann dies ein Sicherheitsrisiko darstellen.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>parse_ini_string</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- 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
-->