require()

Der require()-Befehl setzt an seine Stelle den Inhalt der angegebenen Datei (ähnlich dem #include von C).

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

Wichtig: PHP kehrt zu Beginn der per include() oder require() eingebundenen Dateien vom PHP- in den HTML-Modus und am Schluss der Datei wieder vom HTML- in den PHP-Modus zurück. Falls innerhalb dieser Dateien also PHP-Code ausgeführt werden soll, muss dieser eingeschlossen werden von gültigen PHP-Start- und PHP-Ende-Marken (siehe gültige PHP-Start- und Ende-Tags).

require() ist keine PHP-Anweisung, sondern eine spezielle Sprachanweisung. Sie ist anderen Regeln unterworfen als Funktionen. Einerseits unterliegt sie keinen Kontroll-Srukturen, andererseits gibt sie keinen Wert zurück. Der Versuch, von einem require()-Aufruf einen Rückgabewert zu erhalten, führt zu einem Parse-Fehler.

Anders als include() wird require() immer die angegebene Datei einlesen, auch dann, wenn die Programmzeile, in der sie steht, nicht ausgeführt wird. Wenn Sie eine Datei nur bedingt einlesen wollen, benutzen Sie include(). Die bedingte Anweisung würde require() nicht davon abhalten, die Datei zu laden.

Innerhalb von Schleifen tritt der Effekt auf, dass, obwohl die den require()-Befehl enthaltende Zeile mehrfach angesprungen wird, die entsprechende Datei trotzdem nur genau einmal eingelesen (ausgeführt) wird.

Sie können also require() nicht innerhalb von Programm-Schleifen einsetzen. Deshalb, und wenn Sie verschiedene Dateien einlesen wollen, müssen Sie in Schleifen den Befehl include() benutzen.

require ('header.inc');

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

Wird die mittels require() 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. */
require ("http://someserver/file.txt?vareins=1&varzwei=2");

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

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

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

In PHP 3 ist es möglich, eine return-Anweisung innerhalb einer per require() eingebundenen Datei auszuführen, solange diese Anweisung im Hauptteil dieser Datei steht. Die return-Anweisung darf nicht in Blöcken (also innerhalb von geschwungenen Klammern "{}" stehen. In PHP 4 existiert diese Möglichkeit nicht mehr. Wenn Sie diese dennoch benötigen, sehen Sie unter include() nach.

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