include

Die PHP-Anweisung include

include lädt den Inhalt einer anderen PHP-Datei in das aktuelle Skript und führt ihn an der Stelle aus, an der die Anweisung steht. Konzeptionell kopiert PHP die eingebundene Datei an Ort und Stelle, wertet sie im gleichen Gültigkeitsbereich aus und setzt dann fort. So vermeidet man die Wiederholung gemeinsam genutzter Bausteine und Logik — Kopfzeilen, Fußzeilen, Navigation, Konfiguration und wiederverwendbare Funktionen — auf vielen Seiten.

Diese Seite behandelt die Syntax, wie der Gültigkeitsbereich funktioniert, was include zurückgibt, wie es sich von require unterscheidet und welche häufigen Fehler zu vermeiden sind.

Syntax

include 'filename.php';

Der Pfad kann relativ oder absolut sein. include ist ein Sprachkonstrukt, keine Funktion, daher sind die Klammern optional — sowohl include 'file.php'; als auch include('file.php'); funktionieren.

Wenn PHP ein include ausführt, sucht es nach der Datei in dieser Reihenfolge: der angegebene Pfad (bei relativen Pfaden aufgelöst gegen das aktuelle Arbeitsverzeichnis und die include_path-Einstellung), dann das Verzeichnis des laufenden Skripts. Um Includes unabhängig davon zu machen, von wo aus das Einstiegsskript aufgerufen wird, sollte man sie am aktuellen Dateiort verankern:

include __DIR__ . '/partials/header.php';

__DIR__ ist das Verzeichnis der Datei, die die Anweisung enthält, sodass der Include korrekt aufgelöst wird, selbst wenn das Skript aus einem anderen Verzeichnis heraus aufgerufen wird.

Ein funktionierendes Beispiel

Da include auf separaten Dateien arbeitet, ist es am übersichtlichsten, diese Dateien zur Laufzeit zu erstellen. Das folgende Snippet schreibt ein kleines Partial, bindet es ein und gibt das Ergebnis aus — es ist als einzelnes Skript vollständig ausführbar:

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

Die eingebundene Datei kann $name lesen, weil include den umgebenden Gültigkeitsbereich teilt. Das ist das Wichtigste, was man über include verstehen sollte: Es handelt sich nicht um ein isoliertes Modulsystem. Alle Variablen, die vor dem include existieren, sind für die eingebundene Datei verfügbar, und alle Variablen, die die eingebundene Datei definiert, sind anschließend auch im Aufrufer sichtbar.

Einen Wert aus einer eingebundenen Datei zurückgeben

Eine eingebundene Datei kann einen Wert per return zurückgeben, der dann das Ergebnis des include-Ausdrucks wird. Das ist die idiomatische Methode, um Konfigurationen zu laden:

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Wenn die eingebundene Datei kein return enthält, ergibt der include-Ausdruck bei Erfolg 1.

include vs. require (und die _once-Varianten)

PHP hat vier verwandte Anweisungen. Sie alle laden eine Datei ein; sie unterscheiden sich darin, was bei einem Fehler passiert und ob doppelte Einbindungen übersprungen werden.

Faustregeln:

• Verwende require für Dateien, ohne die das Skript nicht ausgeführt werden kann (eine Konfigurationsdatei, eine Klassendefinition, eine Datenbankverbindung). Bei einem fatalen Fehler sofort abzubrechen ist sicherer als in einem defekten Zustand fortzufahren.
• Verwende include für optionale Teile, wie ein Sidebar-Widget oder einen Werbeblock, bei dem eine fehlende Datei nicht die gesamte Seite zum Absturz bringen sollte.
• Verwende die _once-Varianten, wenn das erneute Einbinden einer Datei Fehler verursachen würde — am häufigsten dann, wenn die Datei Funktionen oder Klassen deklariert, da deren erneute Deklaration ein fataler Fehler ist.

Häufige Fehlerquellen

• Benutzereingaben in einem Pfad vertrauen. Niemals ungefilterte Anfragedaten an include übergeben (zum Beispiel include $_GET['page'] . '.php';). Das öffnet die Tür für Local-File-Inclusion-Angriffe. Stattdessen gegen eine Positivliste bekannter Dateien validieren.
• Relative Pfade, die versagen. Ein bloßes include 'header.php'; hängt vom aktuellen Arbeitsverzeichnis ab und kann fehlschlagen, wenn das Skript von einem anderen Ort aus aufgerufen wird. Bevorzuge __DIR__-verankerte Pfade.
• Erneutes Deklarieren von Funktionen oder Klassen. Wenn eine Datei, die Funktionen definiert, zweimal per einfachem include eingebunden wird, wirft PHP einen fatalen "Cannot redeclare"-Fehler. Verwende für solche Dateien include_once.
• Isolation annehmen. Da der Gültigkeitsbereich geteilt wird, kann eine eingebundene Datei eigene Variablen überschreiben. Includes sollten fokussiert und vorhersehbar bleiben.

Warum include verwenden

• Wiederverwendbarkeit — gemeinsam genutzte Bausteine oder Logik einmal definieren und in jede Seite einbinden, die sie benötigt.
• Wartbarkeit — die Navigation in einem Partial ändern und alle Seiten aktualisieren sich.
• Struktur — eine große Anwendung in kleine, fokussierte Dateien aufteilen statt in einen Monolithen.

Verwandte Themen

• PHP require und require_once — die fehlerintolerantere Variante.
• PHP include_once — eine Datei höchstens einmal einbinden.
• PHP Functions — was typischerweise in gemeinsam genutzten, eingebundenen Dateien steht.
• PHP File Handling — Dateien zur Laufzeit lesen und schreiben.

Practice