Wie in vielen anderen Programmiersprachen auch, kann man in PHP Code aus anderen Dateien in den Quelltext einbinden. So können längere Quelltexte aufgeteilt oder zum Beispiel Klassen oder Funktionen in eigene Dateien ausgelagert werden. Mittels der include-Anweisung können diese Dateien dann in den Quelltext eingebunden werden. Wie das Inkludieren funktioniert und welche Anweisungen zum Einbinden von Dateien es noch gibt, erkläre ich in diesem Artikel.

Eine include-Anweisung sieht beispielsweise so aus:

hallo.php:
<?php
echo "Hallo";
include 'welt.php';
?>
 
welt.php:
<?php
echo " Welt!";
?>

Wenn man die hallo.php nun aufruft, würde Hallo Welt! ausgegeben werden. Der Inhalt der welt.php wurde an der Stelle von include 'welt.php' eingefügt (auch: inkludiert, oder eingebunden).

Die include-Anweisung ist ein Sprachkonstrukt, und keine Funktion! Deswegen kann sie auch ohne Klammern geschrieben werden, das sollte man sich auch angewöhnen, denn es gibt Fälle in denen die Klammern weggelassen werden müssen.

Anweisungen zum Einbinden von Dateien

Es gibt 4 Anweisungen zum Einbinden von Dateien: include, require, include_once und require_once.

• Wenn eine mittels include eingebundene Datei nicht gefunden wurde, wird eine Warnung ausgegeben. Wurde die Datei mittels require eingebunden, wird zusätzlich zu der Warnung noch ein Fataler Fehler ausgegeben, wodurch die Skriptausführung abgebrochen wird.
• include_once und require_once inkludieren eine Datei nur wenn sie noch nicht inkludiert wurde, das ist nützlich um zu vermeiden das Variablen, Funktionen oder Klassen mehrmals definiert werden (was zu einem Fehler führen würde).

Funktionsweise: Inkludieren

Wenn eine Datei inkludiert wird, springt der PHP-Interpreter am Anfang der inkludierten Datei aus dem Parse-Modus raus, und setzt das Parsen erst am Ende der inkludierten Datei fort. Wenn man also PHP-Quelltext inkludieren möchte, muss man auch in der zu inkludierenden Datei Start- und Endtags (<?php und ?>) einfügen, ansonsten wird der Quelltext vom PHP-Interpreter nicht interpretiert (also nur ausgegeben).

Wenn bei der Interpretation der inkludierten Datei ein Fehler auftritt, beispielsweise aufgrund eines Syntax-Fehlers (z.B. einem vergessenen Semikolon), wird die Ausführung des kompletten Skripts beendet.

Der include_path

Der include_path gibt an, wo PHP die zu inkludierende Datei suchen soll, dabei können auch mehrere Pfade angegeben werden. Wenn eine Datei inkludiert wird, sucht PHP sie unter den im include_path angegebenen relativen Pfaden, zuerst relativ zum Arbeitsverzeichnis, danach relativ zu dem Verzeichnis in dem sich das aktuelle Skript befindet. Danach werden die absoluten Pfade im include_path durchsucht.

• Der aktuelle include_path kann mittels der Funktion get_include_path() abgefragt werden. Die Funktion liefert den/die Pfade als Zeichenkette, getrennt durch Doppelpunkte (Linux/Unix) bzw. Semikolons (Windows) zurück.
• Mit set_include_path(string $pfad) lässt sich der include_path ändern, die Konstante PATH_SEPARATOR kann verwendet werden um die einzelnen Pfade zu trennen, da ja unter Windows andere Separatoren (Semikolons) als unter Linux/Unix verwendet werden.
• Das aktuelle Arbeitsverzeichnis lässt sich mit der Funktion getcwd() ermitteln. Normalerweise ist es das Verzeichnis, in dem die vom Benutzer aufgerufene Datei liegt.

Ein kleines Beispiel:

/htdocs/test/index.php:
<?php
echo get_cwd();                // Arbeitsverzeichnis: /htdocs/test/
echo get_include_path();       // include_path: .:bla:/lib/php
                               // (also . und bla und /lib/php)
include 'classes/test.php';
?>
 
htdocs/test/classes/test.php:
<?php
include 'bla.php';             // (befindet sich ebenfalls in classes/)
 
?>

In diesem Beispiel würde PHP wie folgt vorgehen:

Sobald die Datei gefunden wurde, wird sie inkludiert, PHP sucht dann natürlich nicht mehr weiter.

Was hat es mit . und .. auf sich?

Der Punkt steht unter Unix/Linux für das aktuelle Verzeichnis, .. steht für das übergeordnete Verzeichnis. Der Pfad /test/./xyz hat die selbe Bedeutung wie /test/xyz, /test/../xyz wäre aber /xyz. Obwohl sie eigentlich aus der Unix-Welt kommen, funktionieren . und .. auch, wenn man PHP unter Windows benutzt. Übrigens: Wenn man vor den Pfad einer inkludierten Datei einen . bzw. .. setzt, wird der include_path ignoriert, PHP sucht dann relativ zum Skript-Verzeichnis nach der Datei.

include './datei_im_selben_verzeichnis.php';
include '../datei_im_uebergeordneten_verzeichnis.php';

Der Geltungsbereich von Variablen

Inkludierte Dateien übernehmen den Geltungsbereich von der Stelle, an der sie inkludiert werden. Alles was im dortigen Geltungsbereich liegt, ist auch in der inkludierten Datei verfügbar. Variablen die in der inkludierten Datei definiert werden übernehmen ebenfalls den Geltungsbereich von der Stelle an der die Datei inkludiert wurde. Alle Klassen und Funktionen die in der inkludierten Datei definiert werden, sind aber global sichtbar.

hallowelt.php:
<?php
function hallo() {
    $hallo = "Hallo Welt!";
    include 'ausgeben.php';
    var_dump($ausgegeben); // bool(true)
}
hallo();
var_dump($ausgegeben); // NULL
?>
ausgeben.php:
<?php
echo $hallowelt; // Hallo Welt!
$ausgegeben = true;
?>

Entfernte Dateien

Wenn in der PHP-Konfigurationsdatei allow_url_fopen und allow_url_include aktiviert sind, ist es auch möglich Dateien von anderen Servern zu inkludieren. Diese Dateien werden auch von PHP interpretiert, d.h. enthaltener PHP-Quelltext wird ausgeführt!

include 'http://www.example.com/skript.php';

Hierbei muss man allerdings beachten, das der Server auf dem die zu inkludierende Datei liegt, den PHP-Quelltext nicht schon interpretiert bzw. das der Server auch PHP-Quelltext ausgibt.

Rückgabewerte

Innerhalb einer inkludierten Datei kann man wie bei Funktionen mit return zurückspringen, es ist auch möglich ein Ergebnis bzw. einen Rückgabewert zu übergeben. Wenn eine inkludierte Datei keinen Rückgabewert mittels return zurückgibt, gibt include 1 zurück (Inkludieren erfolgreich) oder false (Inkludieren nicht erfolgreich, z.B. wenn die Datei nicht gefunden wurde).

test.php:
<?php
$ergebnis = include 'berechnung.php';
echo $ergebnis; // 42
?>
berechnung.php:
<?php
$zahl = 40 + 2;
return $zahl;
echo "Das hier wird nie ausgegeben.";
?>

Bei entfernten Dateien geht das allerdings nicht (so einfach). Man kann aber auch bei entfernten Dateien Werte zurückgeben, indem man sie einfach als Variablen definiert. In inkludierten Dateien definierte Variablen sind ja auch in der Datei die sie inkludieren verfügbar.

<?php $rueckgabewert = 42; ?>

Wenn man mit dem Rückgabewert einer inkludierten Datei arbeitet, sollte man darauf achten, dass man die include-Anweisung ohne Klammern schreibt, in manchen Fällen kann es sonst dazu kommen das PHP die Anweisung falsch interpretiert.

// So ist es falsch! PHP würde hier folgendes tun:
// ('berechnung.php') mit 42 vergleichen = false (sind nicht gleich)
// include erwartet eine Zeichenkette, false wird zu einer Zeichenkette umgewandelt,
// dabei kommt '' (leere Zeichenkette) raus.
// dann würde PHP versuchen '' zu inkludieren, das klappt nicht.
// include gibt false zurück, der Code in der if-Bedingung wird nicht ausgeführt.
if (include('berechnung.php') == 42) {
    echo "Ergebnis stimmt!";
}
// So funktioniert es richtig.
if ((include 'berechnung.php') == 42) {
    echo "Ergebnis stimmt!";
}

Automatisches Anhängen/Voranstellen von Dateien

Man kann PHP so konfigurieren, das an jede interpretierte Datei eine Datei angehängt bzw. vorangestellt wird, als würde sie am Anfang bzw. am Ende der Datei mittels der require-Anweisung inkludiert werden. Dazu trägt man in der php.ini bei den Optionen auto_prepend_file (Voranstellen) bzw. auto_append_file (Anhängen) den Pfad zu der entsprechenden Datei ein. Der include_path wird beim Inkludieren der Dateien beachtet.

; Automatically add files before or after any PHP document.
auto_prepend_file = /htdocs/header.php
auto_append_file = /htdocs/footer.php

Wenn dort nichts oder none steht, wird keine Datei angehängt bzw. vorangestellt.

Hinweis: Wenn das PHP-Skript mit der Funktion exit() beendet wird, wird keine Datei angehangen.

Automatisches Nachladen von Klassen

Wenn man objektorientierte Anwendungen schreibt, hat man oft viele Quelldateien, eine für jede Klasse. Am Anfang einer Datei steht meist eine lange Liste von include-Anweisungen, um alle benötigten Klassendefinitionen zu laden. Mit PHP 5 ist es auch möglich Klassen dynamisch nachzuladen, dazu wird die __autoload-Funktion verwendet. Wenn PHP bei der Interpretation des Quelltextes auf eine noch nicht definierte Klasse stößt und es eine __autoload-Funktion gibt, ruft es Funktion auf, in der dann die Quelldatei für die entsprechende Klasse gesucht und inkludiert wird. So spart man sich eine Menge Schreibarbeit.

Automatisches Nachladen von Klassen mit PHP

Die Geschwindigkeit

Jan Walther hat in seinem PHP-Performance-Blog zwei interessante Artikel geschrieben bei deinen es um die Geschwindigkeit der Anweisungen zum Inkludieren von Dateien geht. Im ersten Artikel PHP-Dateien in andere Scripts einbinden analysiert er die Geschwindigkeit von include, require, include_once und require_once, und kommt zum Schluss das es keine merklichen Unterschiede gibt.

Im Artikel Dateien performant einfügen beschreibt er die Unterschiede zwischen absoluten, semiabsoluten und relativen Pfaden, und wie sie sich auf die Geschwindigkeit auswirken. Außerdem beschreibt er eine Methode, mit der sich Dateien mit ihrem absoluten Pfad inkludieren lassen, ohne das man dabei auf die Flexibilität von relativen Pfaden verzichten muss.

• Der Trinitäts-Operator
• Dateinamen-Zeichensatz korrigieren mit convmv
• Der Alternative PHP Cache
• APC: Status und Überwachung
• Funktionen von APC