svn: /phpdoc/de/trunk/language/control-structures/ include.xml

Added: phpdoc/de/trunk/language/control-structures/include.xml
===================================================================
--- phpdoc/de/trunk/language/control-structures/include.xml	                        (rev 0)
+++ phpdoc/de/trunk/language/control-structures/include.xml	2010-05-24 15:47:19 UTC (rev 299696)
@@ -0,0 +1,338 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 288721 $ -->
+<!-- EN-Revision: 288721 Maintainer: raphaelm Status: ready -->
+
+<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title><function>include</function></title>
+ <simpara>
+  <function>include</function> bindet eine angegebene Datei ein und
+  führt sie aus.
+ </simpara>
+ <simpara>
+  Die folgende Dokumentation trifft ebenfalls auf <function>require</function>
+  zu.
+ </simpara>
+ <simpara>
+  Dateien werden unter dem angegebenen Pfad gesucht, oder, wenn keiner
+  gegeben ist, im <link linkend="ini.include-path">include_path</link>.
+  Wenn keine Datei gefunden wurde, erzeugt <function>include</function>
+  eine <link linkend="errorfunc.constants.errorlevels.e-warning">Warnung</link>,
+  im Gegensatz dazu erzeugt <function>require</function> in diesem Fall einen
+  <link linkend="errorfunc.constants.errorlevels.e-error">Fatal Error</link>.
+ </simpara>
+ <simpara>
+  Wenn ein Pfad angegeben ist (absolut oder relativ), wird der
+  <link linkend="ini.include-path">include_path</link> ignoriert. Wenn der
+  Dateiname beispielsweise mit <literal>../</literal> befinnt, sucht der
+  Parser im übergeordneten Verzeichnis des aktuellen Arbeitsverzeichnisses
+  nach der Datei.
+ </simpara>
+ <simpara>
+  Mehr Informationen über den Umgang PHPs mit dem Einbinden von Dateien
+  im Zusammenhang mit dem include_path, siehe die Dokumentation zu
+  <link linkend="ini.include-path">include_path</link>.
+ </simpara>
+ <simpara>
+  Wenn eine Datei eingebunden wird, wird für den enthaltenen Code der gleiche
+  <link linkend="language.variables.scope">Geltungsbereich</link> für
+  Variablen übernommen, der für die Zeile gilt, die den include-Befehl
+  aufruft. Jede für diese Zeile verfügbare Variable ist in dem eingebundenen
+  Code verfügbar und jede Variable, die in der eingebundenen Datei gesetzt wird,
+  steht dem weiteren aufrufenden Skript zur Verfügung, als wäre sie in der
+  Zeile, in der include aufgerufen wird, definiert worden.
+  Alle Funktionen und Klassen in der eingebundenen Datei gehören zum globalen
+  Geltungsbereich.
+ </simpara>
+ <para>
+  <example>
+   <title>Grundlegendes <function>include</function>-Beispiel</title>
+   <programlisting role="php">
+<![CDATA[
+vars.php
+<?php
+
+$farbe = 'grün';
+$frucht = 'Apfel';
+
+?>
+
+test.php
+<?php
+
+echo "Der $frucht ist $farbe."; // Der  ist s .
+
+include 'vars.php';
+
+echo "Der $frucht ist $farbe"; // Der Apfel ist grün
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <simpara>
+  Wenn include innerhalb einer Funktion aufgerufen wird, verhält sich der
+  gesamte Code aus der aufgerufenen Datei wie wenn er in der Funktion stände.
+  Folglich hat er den selbern Variablen-Gültigkeitsbereich wie diese
+  Funktion.
+  Eine Ausname von dieser Regel sind <link
+  linkend="language.constants.predefined">Magische Konstanten</link>,
+  die geparst werden, bevor die Einbindung durchgeführt wird.
+ </simpara>
+ <para>
+  <example>
+   <title>Include in Funktionen</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+function foo()
+{
+    global $farbe;
+
+    include 'vars.php';
+
+    echo "Der $frucht ist $farbe.";
+}
+
+/* vars.php ist im Gültigkeitsbereich von foo(),  *
+ * sodass $frucht außerhalb von diesem Bereich    *
+ * nicht verfügbar ist. $farbe ist auch außerhalb *
+ * verfügbar, weil es als global deklariert ist.  */
+
+foo();                            // Der Apfel ist grün.
+echo "Der $frucht ist $farbe.";   // Der  ist grün.
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <simpara>
+  Wenn eine Datei eingebunden wird, wechselt der Parser am Anfang
+  der eingebundenen Datei in den HTML-Modus und am Ende wieder in
+  den PHP-Modus. Aus diesem Grund muss jeder PHP-Code in der eingebundenen
+  Datei mit <link linkend="language.basic-syntax.phpmode">gültigen PHP
+  Start- und Endtags</link> umschlossen sein.
+ </simpara>
+ <simpara>
+  Wenn "<link linkend="ini.allow-url-fopen">fopen-URL-Wrapper</link>"
+  aktiviert sind (was sie in der Standard-Konfiguration sind), kann die
+  einzubindende Datei mit einer URL (über HTTP oder ein anderes unterstütztes
+  Protokoll - siehe <xref linkend="wrappers"/> für eine Liste unterstützter
+  Protokolle) anstall einem lokalen Pfad eingebunden werden. Wenn der
+  Zielserver die Zieldatei als PHP-Code interpretiert, können Variablen
+  an die einzubindende Datei mithilfe von HTTP-GET-Query-Strings übergeben
+  werden, obwohl dies nicht das selbe ist, wie wenn man die Datei einbindet
+  und sie den Variablenbereich übernimmt; das Skript läuft weiterhin auf dem
+  entfernten Server und das Ergebnis wird in das lokale Skript eingebunden.
+ </simpara>
+ &warn.no-win32-fopen-wrapper;
+ <para>
+  <example>
+   <title><function>include</function> über HTTP</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+/* Dieses Beispiel setzt vorraus, dass www.example.com konfiguriert ist *
+ * .php-Dateien als PHP-Skripte zu interpretieren und .txt-Dateien      *
+ * nicht. Desweiteren meint 'Funktioniert' hier, dass die Variablen     *
+ * $foo und $bar innerhalb der eingebundenen Datei verfügbar sind       */
+
+// Funktioniert nicht; file.txt wird von www.example.com nicht als PHP interpretiert
+include 'http://www.example.com/file.txt?foo=1&bar=2';
+
+// Funktioniert nicht; hier wird nach einer Datei mit dem Namen
+// 'file.php?foo=1&bar=2' im lokalen Dateisystem gesucht.
+include 'file.php?foo=1&bar=2';
+
+// Funktioniert
+include 'http://www.example.com/file.php?foo=1&bar=2';
+
+$foo = 1;
+$bar = 2;
+include 'file.txt';  // Funktioniert
+include 'file.php';  // Funktioniert
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <warning>
+  <title>Sicherheits-Warnung</title>
+  <para>
+   Die entfernte Datei mag vom entfernten Server (je nach Konfiguration)
+   geparst werden oder nicht, aber sie muss weiterhin ein gültiges
+   PHP-Skript ausgeben, weil die Ausgabe auf dem lokalen Server als PHP
+   ausgeführt wird. Wenn die Ausgabe des vom entfernten Server nur
+   ausgegeben werden soll, ist <function>readfile</function> die bessere
+   Wahl. Andernfalls muss sehr gut acht gegeben werden, dass das entfernte
+   Skript sicher gültigen und erwünschten Code ausgibt!
+  </para>
+ </warning>
+ <para>
+  Siehe auch  <link linkend="features.remote-files">Entfernte Dateien</link>,
+  <function>fopen</function> und <function>file</function> für verwandte
+  Informationen.
+ </para>
+ <simpara>
+  Umgang mit Rückgabewerten: Es ist möglich, in der eingebundenen Datei
+  <function>return</function> aufzurufen um den Ablauf dieser Datei
+  abzubrechen und zu dem einbindenden Skript zurückzukehren. Der
+  zurückgegebene Wert kann als Rückgabewert des include-Aufrufs abgefragt
+  werden, wie bei einer normalen Funktion. Dies ist beim Einbinden
+  entfernter Dateien nur möglich, wenn die entfernte Datei mit
+  <link linkend="language.basic-syntax.phpmode">gültigen PHP Start- und Endtags</link>
+  umschlossen ist (wie bei jeder lokalen Datei). Es ist möglich, die
+  benötigten Variablen innerhalb diese Tags zu deklarieren und sie werden
+  im einzubindenden Skript am dem Punkt, an dem die Datei eingebunden wird,
+  verfügbar.
+ </simpara>
+ <para>
+  Weil <function>include</function> eine spezielles Sprachkonstrukt ist,
+  sind die Klammern um das Argument optional. Beim vergleichen des
+  Rückgabewerts muss allerdings aufgepasst werden (siehe Beispiel).
+  <example>
+   <title>Comparing return value of include</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// funktioniert nicht, wird als include(('vars.php') == 'OK') behandelt
+// also als include('')
+if (include('vars.php') == 'OK') {
+    echo 'OK';
+}
+
+// Funktioniert
+if ((include 'vars.php') == 'OK') {
+    echo 'OK';
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <para>
+  <example>
+   <title><function>include</function> und <function>return</function></title>
+   <programlisting role="php">
+<![CDATA[
+return.php
+<?php
+
+$var = 'PHP';
+
+return $var;
+
+?>
+
+noreturn.php
+<?php
+
+$var = 'PHP';
+
+?>
+
+testreturns.php
+<?php
+
+$foo = include 'return.php';
+
+echo $foo; // gibt 'PHP' aus
+
+$bar = include 'noreturn.php';
+
+echo $bar; // gibt 1 aus
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <simpara>
+  <literal>$bar</literal> hat den Wert <literal>1</literal> weil das Einbinden
+  erfolgreich war. Die erste Datei nutzt <function>return</function>,
+  was die andere nicht tut. Wenn das Einbinden fehlschlägt, wird &false;
+  zurückgegeben und ein Fehler der Kategorie <constant>E_WARNING</constant>
+  erzeugt.
+ </simpara>
+ <para>
+  Wenn in der eingebundenen Datei Funktionen definiert werden, können sie
+  in der einbindenden Datei genutzt werden, unabhängig davon, ob sie vor
+  oder nach <function>return</function> definiert werden. Wenn eine Datei
+  zweimal eingebunden wird, erzeugt PHP 5 einen fatalen Fehler weil
+  Funktionen bereits definiert wurden, während PHP 4 Funktionen, die nach
+  <function>return</function> definiert werden, ignoriert.
+  Es ist empfohlen, <function>include_once</function> zu nutzen anstatt
+  zu überprüfen ob die Datei bereits eingebunden wurde und abhängig davon
+  innerhalb der eingebundenen Datei zu handeln.
+ </para>
+ <simpara>
+  Ein anderer Weg, die Ausgabe eines eingebundenen Skriptes in eine
+  Variable zu schreiben, ist das Arbeiten mit den
+  <link linkend="ref.outcontrol">Funktionen zur Steuerung des Ausgabepuffers</link>.
+  Beispiel:
+ </simpara>
+ <para>
+  <example>
+   <title>Nutzung des Ausgabepuffers um eine Datei "in einen String" einzubinden</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = get_include_contents('somefile.php');
+
+function get_include_contents($filename) {
+    if (is_file($filename)) {
+        ob_start();
+        include $filename;
+        $contents = ob_get_contents();
+        ob_end_clean();
+        return $contents;
+    }
+    return false;
+}
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </para>
+ <para>
+  Um automatisch Dateien in Skripte einzubinden, siehe auch die Konfigurationsdirektiven
+  <link linkend="ini.auto-prepend-file">auto_prepend_file</link> und
+  <link linkend="ini.auto-append-file">auto_append_file</link>
+  in &php.ini;.
+ </para>
+
+ &note.language-construct;
+
+ <simpara>
+  Siehe auch <function>require</function>, <function>require_once</function>,
+  <function>include_once</function>, <function>get_included_files</function>,
+  <function>readfile</function>, <function>virtual</function>, und
+  <link linkend="ini.include-path">include_path</link>.
+ </simpara>
+</sect1>
+
+<!-- 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
+-->


Property changes on: phpdoc/de/trunk/language/control-structures/include.xml
___________________________________________________________________
Added: svn:executable
   + *