Function.include

Aus PHP-Wiki

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 vor PHP 4.3.5 nicht unterbricht. Beginnend mit PHP 4.3.5 wird das Skript in diesem Fall abgebrochen. 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/. Beginnt der Pfad mit ../ so wird der include_path nur relativ zum aktuellen Verzeichnis durchsucht. 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 #1 Grundlegendes include() Beispiel vars.php
<?php

$color = 'grüner';
$fruit = 'Apfel';

?>

test.php
<?php

echo "Ein $color $fruit"; // Ein

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 #2 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 List of Supported Protocols/Wrappers) 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. WarnungPHP Versionen kleiner 4.3.0 für Windows, erlauben den Zugriff auf Remote-Dateien mit dieser Funktion nicht, selbst wenn allow_url_fopen aktiviert ist. Beispiel #3 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 #4 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. Da include() ein spezielles Sprachkonstrukt ist kann das Argument auch ohne Klammern übergeben werden. Sie sollten dies beachten falls Sie den Rückgabewert vergleichen wollen. Beispiel #5 Prüfung des Rückgabewerts von include <?php
// das folgende funktioniert nicht, es wird als
// include(('vars.php') == 'OK'), d.h. include(), ausgewertet
if (include('vars.php') == 'OK') {
    echo 'OK';
}

// das folgende funktioniert
if ((include 'vars.php') == 'OK') {
    echo 'OK';
}
?> Hinweis: In PHP 3 darf eine return-Anweisung nicht innerhalb eines Blocks auftreten, es sei denn, es ist ein Funktionsblock. In diesem Fall gilt return() für diese Funktion und nicht für die ganze Datei. Beispiel #6 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. Kann die Datei nicht eingebunden werden wird FALSE zurückgegeben und eine E_WARNING Warnung ausgegeben. Funktionen die innerhalb einer Include-Datei definiert werden können unabhängig davon ob sie vor oder nach der return() Anweisung stehen in der Hauptdatei benutzt werden. PHP 5 bricht mit einem fatalen Fehler ab wenn die Datei zweimal eingebunden wird da die enthaltenen Funktionen bereits definiert sind, PHP 4 dagegen ignoriert funktionen die nach der return() Anweisung definiert werden. Es wird empfohlen include_once() zu benutzen und nicht selbst innerhalb der eingebundenen Datei zu prüfen ob die Datei bereits eingebunden wurde und mit einer bedingten return Anweisung abzubrechen. Weitere Möglichkeiten Dateien in Variablen "einzubinden" bieten ihnen die Funktionen fopen() und file() oder include() im Zusammenspiel mit den Funktionen zur Ausgabesteuerung. Hinweis: Da dies ein Sprachkonstrukt und keine Funktion ist, deshalb können Sie dieses nicht mit Variablenfunktionen verwenden. Siehe auch require(), require_once(), include_once(), readfile(), virtual()und include_path.