include()

Die include() Anweisung bindet die angegebene Datei ein und wertet diese aus.

Die untenstehende Dokumentation gilt ebenso für require(). Diese beiden Konstrukte sind in jeder Hinsicht gleichwertig mit der einen Ausnahme: der Umgang mit Fehlern. include() erzeugt ein Warning während require() in einem Fatal Error endet. Mit anderen Worten, verwenden Sie require(), wenn Sie möchten, dass eine fehlende Datei die Ausführung ihres Skripts beendet. include() verhält sich anders, ihr Skript wird weiterhin ausgeführt. Stellen Sie außerdem sicher, dass Sie einen gültigen include_path gesetzt haben. Beachten Sie, dass eine Parse Error in einer Datei, die mit require eingebunden wurde, die Ausführung ihre Skripts nicht unterbricht.

Dateien die mit include eingebunden werden, werden zuerst im include_path relativ zum gegenwärtigen Arbeitsverzeichnis gesucht und danach im include_path relativ zum Verzeichnis des ausgeführten Skripts. Zur Veranschaulichung: Falls Ihr include_path . entspricht, ist das gegenwärtige Arbeitsverzeichnis /www/. Sie haben über include include/a.php eingebunden und in diesem Skript steht die Anweisung include "b.php". In diesem Fall wird b.php zuerst im Verzeichnis /www/ gesucht und danach im Verzeichnis /www/include/.

Wenn eine Datei eingebunden wird, erbt der enthaltene Code den Geltungsbereich von Variablen der Zeile in der die Anweisung steht. Ab dieser Zeile stehen alle verfügbaren Variablen in der aufgerufenen Datei im aufrufenden Skript zur Verfügung.

Beispiel 16-3. Grundlegendes include() Beispiel vars.php <?php $color = 'grün'; $fruit = 'Apfel'; ?> test.php <?php echo "Ein $color $fruit"; // A include 'vars.php'; echo "Ein $color $fruit"; // Ein grüner Apfel ?>

Steht include im aufrufenden Skript innerhalb einer Funktion, verhält sich der gesamte Code der aufgerufenen Datei genau so, als ob Sie diesen Code innerhalb dieser Funktion definiert hätten. Aus diesem Grund hat dieser Code den Geltungsbereich der Variablen dieser Funktion.

Beispiel 16-4. Include innerhalb einer Funktion <?php function foo() { global $color;     include 'vars.php';     echo "Ein $color $fruit"; } /* vars.php ist im Geltungsbereich von foo(),  * * d.h. $fruit steht außerhalb dieses Bereichs * * NICHT zur Verfügung. $color schon, da wir   * * diese Variable als global definiert haben  */ foo();                    // Ein grüner Apfel echo "Ein $color $fruit";   // Ein grüner ?>

Beim Einbinden einer Datei wechselt der Parser vom PHP-Modus zu Beginn der Zieldatei in den HTML-Modus und kehrt am Ende der eingebunden Datei wieder in den PHP-Modus zurück. Deshalb muss jeglicher Code innerhalb der eingebundenen Datei, der als PHP-Code ausgeführt werden soll, von gültigen PHP-Start- und Ende-Tags eingefaßt sein.

Wenn "URL fopen wrappers" in PHP aktiviert sind (in der Standardkonfiguration ist das der Fall) können Sie als Pfad der einzubindenden Datei auch eine URL (via HTTP oder anderen unterstützen Wrappern - eine Liste der unterstützen Protokolle finden Sie unter Anhang L) statt einer lokalen Pfadangabe angeben. Falls der Zielserver die Zieldatei als PHP-Code interpretiert, können Sie an die einzubindende Datei Variablen in einem Request-String übergeben, genauso wie bei HTTP GET. Streng genommen ist das nicht das Gleiche, wie diese Datei einzubinden und diesem den Geltungsbereich des Vater-Skripts zu vererben; das Skript wird auf dem Remote-Server ausgeführt und danach wird das Ergebnis in das lokale Skript eingebunden.

Beispiel 16-5. include() über HTTP <?php /* Dieses Beispiel geht davon aus, dass www.example.com so konfiguriert     * * ist, dass .php-Dateien geparst werden und keine .txt Dateien. Also meint * * 'Funkt' hier, dass die Variablen $foo und $bar innerhalb der             * * angeforderten Datei zur Verfügung stehen                                 */ // Funkt nicht; file.txt wird von www.example.com nicht als PHP geparst include 'http://www.example.com/file.txt?foo=1&bar=2'; // Funkt nicht; schaut nach einer lokalen Datei namens // 'file.php?foo=1&bar=2' im lokalen Dateisystem include 'file.php?foo=1&bar=2'; // Funkt include 'http://www.example.com/file.php?foo=1&bar=2'; $foo = 1; $bar = 2; include 'file.txt';  // Funkt include 'file.php';  // Funkt ?>

Siehe auch Zugriff auf entfernte Dateien, fopen() und file() für verwandte Informationen.

Da include() und require() spezielle Sprachkonstrukte sind, müssen Sie diese innerhalb einer bedingten Anweisung in einen Anweisungsblock setzen.

Beispiel 16-6. include() und bedingte Blöcke <?php // Das ist FALSCH und führt nicht zum gewünschten Ergebnis. if ($bedingung)     include $datei; else     include $andere_datei; // Das ist KORREKT. if ($bedingung) {     include $datei; } else {     include $andere_datei; } ?>

Der Umgang mit Returns: Es ist möglich eine return() -Anweisung innerhalb einer eingebunden Datei anzugeben, um die Ausführung innerhalb dieser Datei abzubrechen und zum aufrufenden Skript zurückzukehren. Ebenso ist die Rückgabe von Werten aus einer eingebunden Datei möglich. Sie können den Wert eines include-Aufrufs auf die gleiche Art und Weise nutzen, wie Sie es bei einer Funktion machen würden. Allerdings besteht diese Möglichkeit nicht, wenn Sie entfernte Dateien mittels include einbinden außer, wenn die Ausgabe der entfernten Datei gültige PHP Start- und Endetags beeinhaltet (wie jede lokale Datei auch). Innerhalb dieser Tags können Sie die benötigten Variablen deklarieren und diese werden dann an dem Punkt Ihres Skripts eingeführt, von wo aus der Aufruf mit include erfolgt ist.

Beispiel 16-7. include() und die return() Anweisung 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 ?>

$bar hat den Wert 1, weil include erfolgreich war. Beachten Sie die Unterschiede in den obigen Beispielen. Das erste nutzt return() innerhalb der eingebundenen Datei im Gegensatz zum zweiten Beispiel. Weitere Möglichkeiten Dateien in Variablen "einzubinden" bieten ihnen die Funktionen fopen() und file() oder include() im Zusammenspiel mit den Funktionen zur Ausgabesteuerung.

Siehe auch require(), require_once(), include_once(), readfile(), virtual()und include_path.