include()

Die include()-Anweisung liest die angegebene Datei ein und wertet sie aus.

Wenn die PHP-Konfigurations-Option "URL fopen wrappers" auf enabled (per default) steht, können Sie für die mittels include() eingebundene Datei statt einer lokalen Pfadangabe auch eine URL angeben. Sehen Sie hierzu unter Remote-Dateien und fopen() für weitere Informationen nach.

Wichtig ist, dass beim include()- oder require()-Befehl vom PHP-Parsing-Modus in den HTML-Modus geschaltet wird und bei Rückkehr in das aufrufende Skript wieder zurück vom HTML- in den PHP-Modus. Deshalb muss jeder PHP-Code innerhalb der eingebundenen Dateien umschlossen werden von gültigen PHP-Start- und Ende-Tags.

Das passiert jedes Mal, sobald die include()-Anweisung auftritt. Deshalb können Sie include() auch sehr gut innerhalb von Schleifen verwenden, um eine Anzahl unterschiedlicher Dateien einzubinden.

$files = array ('first.inc', 'second.inc', 'third.inc');
for ($i = 0; $i &lt; count($files); $i++) {
    include $files[$i];
}

include() unterscheidet sich von require() dadurch, dass die include-Anweisung jedesmal neu ausgewertet wird, sobald sie auftritt (und nur zur Ausführungszeit). Dagegen wird die require()-Anweisung beim ersten Auftreten mit der angegebenen Datei ersetzt, egal ob sie einzubinden ist oder nicht (innerhalb von bedingten Anweisungen, z.B. bei if auch dann, wenn das ausgewertete Argument FALSE ergeben hat).

Da include() ein spezieller Sprach-Konstrukt ist, müssen Sie ihn innerhalb einer bedingten Anweisung in einen Anweisungsblock setzen.

/* Das ist falsch und führt nicht zum gewünschten Ergebnis. */
 
if ($Bedingung)
    include($diesedatei);
else
    include($anderedatei);
 
/* Diese ist korrekt. */

if ($Bedingung) {
    include($diesedatei);
} else {
    include($anderedatei);
}

Sowohl in PHP 3 als auch in PHP 4 ist es möglich, eine return-Anweisung innerhalb einer include()eten Datei anzugeben, um die Ausführung dieser Datei abzubrechen und zum aufrufenden-Skript zurück zu kehren. Es gibt aber ein paar Unterschiede in der Arbeitsweise. Der erste ist, dass bei PHP 3 die return-Anweisung nicht innerhalb eines Blocks auftreten darf, es sei denn, es ist ein Funktions-Block. In diesem Fall gilt return für diese Funktion und nicht für die ganze Datei. In PHP 4 gibt es diese Beschränkung nicht. PHP 4 erlaubt ihnen auch die Rückgabe von Werten bei include()eten Dateien. Sie können den Wert des include()-Aufrufs nutzen, als wenn Sie eine Funktion aufgerufen hätten. Das wird in PHP 3 einen Parse-Error ergeben.

Beispiel 11-1. include() in PHP 3 und PHP 4

Beachten Sie, dass die folgende Datei, genannt test.inc im gleichen Verzeichnis wie die Hauptdatei stehen muss:
<?php echo "Vor dem Return <br>\n"; if (1) { return 27; } echo "Nach dem Return <br>\n"; ?>

Die Datei main.html enthält folgendes:
<?php $retval = include ('test.inc'); echo "Datei gibt zurück: '$retval'<br>\n"; ?>

Sobald main.html in PHP 3 aufgerufen wird, wird ein Parse-Error in Zeile 2 angezeigt; Sie können in PHP 3 also keinen Rückgabewert von include() erhalten. In PHP 4 wird das Ergebnis sein:
Vor dem Return Datei gibt zurück: '27'

Die Datei main.html soll nun folgendes enthalten:
<?php include ('test.inc'); echo "Zurück in main.html<br>\n"; ?>

In PHP 4 wird die Ausgabe sein:
Vor dem Return Zurück in main.html
PHP 3 wird dagegen folgendes ausgeben:
Vor dem Return 27Zurück in main.html Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5

Der obige Parse-Error ist das Ergebnis der Tatsache, dass die return-Anweisung innerhalb eines Nicht-Funktions-Blocks von test.inc steht. Wenn das return ausserhalb diese Blocks zu stehen kommt, wird die Ausgabe wie folgt aussehen:
Before the return 27Back in main.html

Die '27' entsteht aus der Tatsache, dass PHP 3 keine solchen Rückgabewerte unterstützt.

Wird eine Datei per include() eingebunden, dann "erbt" der darin enthaltene Code die bis zur Skriptzeile mit der include()-Anweisung definierten Variablen und deren Inhalt. Alle innerhalb der eingebundenen Datei Definitionen von Variablen stehen ab dieser Zeile zur Verfügung. Steht die include()-Anweisung innerhalb einer Funktion, wird der darin stehende Code behandelt, als ob er innerhalb der Funktion stehen würde.

Wird die mittels include() einzubindende Datei über HTTP (fopen wrapper) aufgerufen und sieht der Ziel-Server die Ziel-Datei als PHP-Code ansieht, dann werden die Variablen an die einzubindende Datei wie bei einem HTTP GET übergeben. Das entspricht nicht genau der Einbindung einer lokalen Datei, da das Skript auf dem entfernten Server ausgeführt wird und nur die Ergebnisse in das lokale Skript eingebunden werden.

/* Dieses Beispiel geht davon aus, dass ein beliebiger Server zum 
 * Parsen von *.php-Dateien konfiguriert ist. Also meint 'funkt' hier,
 * dass die Variablen $vareins und $varzwei innerhalb der angeforderten
 * Datei vorhanden sind. */

/* Funkt. nicht; file.txt wird vom besagten Server nicht geparst. */
include ("http://someserver/file.txt?vareins=1&varzwei=2");

/* Funkt. nicht; schaut nach einer lokalen Datei namens 
/* 'file.php?varone=1&vartwo=2' */
include ("file.php?vareins=1&varzwei=2");               

/* Funkt. */
include ("http://someserver/file.php?vareins=1&varzwei=2"); 

$vareins = 1;
$varzwei = 2;
include ("file.txt");    /* Funkt. */
include ("file.php");    /* Funkt. */

Lassen Sie sich nicht durch die Tatsache irritieren, dass Sie Dateien auch über HTTP per require oder include einbinden können (vgl. Remote files). Das oben Gesagte behält seine Gültigkeit.

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