PHP Include

Einführung

PHPs include- und require-Anweisungen ermöglichen es, den Inhalt einer PHP-Datei in eine andere einzufügen, bevor der Server sie ausführt. Dies ist die Grundlage der Code-Wiederverwendung in PHP: Anstatt eine Navigationsleiste, eine Datenbankverbindung oder eine Sammlung von Hilfsfunktionen auf jede Seite zu kopieren, schreibt man sie einmalig in eine separate Datei und bindet sie überall dort ein, wo sie benötigt wird.

Dieses Kapitel behandelt alle vier Einbindungsanweisungen (include, require, include_once, require_once), ihre Unterschiede, das Verhalten von eingebundenen Variablen und Funktionen, häufige Fallstricke sowie Best Practices, die größere Projekte wartbar halten.

Warum Dateieinbindung verwenden

Das Aufteilen von Code in wiederverwendbare Dateien bringt drei konkrete Vorteile:

1. Weniger Wiederholung. Eine Kopf- oder Fußzeile oder einen Konfigurationsblock einmal schreiben und auf beliebig vielen Seiten einbinden. An einer Stelle bearbeiten und alle Seiten werden aktualisiert.
2. Einfachere Wartung. Eine Fehlerbehebung oder eine Designänderung an gemeinsam genutztem Markup findet in einer einzigen Datei statt, nicht über Dutzende von Seiten verteilt.
3. Bessere Organisation. Das Aufteilen eines großen Skripts in kleinere, zweckbenannte Dateien (header.php, db.php, functions.php) macht die Codebasis leichter lesbar und navigierbar.

Die vier Einbindungsanweisungen

PHP bietet vier Anweisungen. Alle kopieren den Inhalt einer Datei in das aktuelle Skript, unterscheiden sich jedoch darin, wie sie mit einer fehlenden Datei umgehen und ob sie eine erneute Einbindung erlauben.

Faustregel: require (oder require_once) für Dateien verwenden, ohne die die Seite nicht funktionieren kann — eine Datenbankverbindung oder eine Klassendefinition. include für optionale Teile verwenden, wie einen Werbeplatz oder eine Seitenleiste, die nützlich, aber nicht kritisch ist.

Grundlegende Syntax

<?php
// Include a file relative to the current script
include __DIR__ . '/header.php';

// Stop the page if a critical file is missing
require __DIR__ . '/db.php';

// Guarantee a file is loaded at most once
require_once __DIR__ . '/functions.php';
?>

__DIR__ ist eine magische Konstante, die zum Verzeichnis der aktuellen Datei aufgelöst wird. Das Erstellen von Pfaden daraus lässt Einbindungen funktionieren, unabhängig davon, aus welchem Verzeichnis das Skript ausgeführt wird — siehe PHP Constants für mehr über magische Konstanten.

Warum _once wichtig ist

Wenn man eine Datei, die eine Funktion oder Klasse definiert, zweimal einbindet, wirft PHP beim zweiten Durchgang einen fatalen Fehler „Cannot redeclare". include_once und require_once verfolgen, welche Dateien bereits geladen wurden, und überspringen Duplikate stillschweigend — sie sind daher der sichere Standard für jede Datei, die Funktionen oder Klassen deklariert.

<?php
require_once __DIR__ . '/functions.php'; // loads it
require_once __DIR__ . '/functions.php'; // skipped — no redeclare error
?>

Variablenbereich in eingebundenen Dateien

Eine eingebundene Datei wird im Gültigkeitsbereich der Zeile ausgeführt, in der sie eingebunden wurde. Variablen, die vor dem include definiert wurden, sind in der eingebundenen Datei verfügbar, und Variablen, die die eingebundene Datei definiert, stehen danach zur Verfügung.

<?php
// config.php
$siteName = "My Site";
$year = 2026;

<?php
// index.php
include __DIR__ . '/config.php';
echo "Welcome to $siteName ($year)";
// Output: Welcome to My Site (2026)
?>

Innerhalb einer Funktion sind die Variablen einer eingebundenen Datei jedoch lokal für diese Funktion. Dies überrascht viele — eine Konfigurationsdatei, die innerhalb einer Funktion eingebunden wird, gibt ihre Variablen nicht an den globalen Gültigkeitsbereich weiter.

Einen Wert aus einer eingebundenen Datei zurückgeben

Eine eingebundene Datei kann einen Wert returnen, was für Konfigurationsarrays praktisch ist:

<?php
// settings.php
return [
    'debug'   => true,
    'timezone' => 'UTC',
];

<?php
// app.php
$config = include __DIR__ . '/settings.php';
echo $config['timezone']; // Output: UTC
?>

Fehlende Dateien elegant behandeln

Mit include löst eine fehlende Datei nur eine Warnung aus, sodass der Rest der Seite weiterhin gerendert wird. Wenn eine Datei optional ist, sollte man zuerst prüfen, ob sie vorhanden ist:

<?php
$sidebar = __DIR__ . '/sidebar.php';

if (file_exists($sidebar)) {
    include $sidebar;
} else {
    echo "<!-- sidebar unavailable -->";
}
?>

Bei Dateien, die die Seite tatsächlich benötigt, ist require vorzuziehen, damit das Skript schnell und deutlich fehlschlägt, anstatt fehlerhafte Ausgaben zu erzeugen.

Best Practices

1. require_once für Code, include für optionale Ausgabe verwenden. Funktions- und Klassendefinitionen sollten niemals zweimal geladen werden; optionale UI-Fragmente können graceful degradieren.
2. Pfade von __DIR__ aus aufbauen. Relative Pfade wie include 'header.php' vermeiden, die vom aktuellen Arbeitsverzeichnis abhängen und unerwartet brechen.
3. Dateien nach Zweck benennen. header.php, footer.php, db.php, auth.php — ein Blick auf den Dateinamen sollte verraten, was darin steckt.
4. Eingebundene Dateien fokussiert halten. Eine Verantwortlichkeit pro Datei macht sie leicht wiederverwendbar und verständlich.
5. Niemals einen aus Benutzereingaben aufgebauten Pfad einbinden (z. B. include $_GET['page']). Dies öffnet eine Local/Remote File Inclusion-Schwachstelle. Stattdessen erlaubte Werte mit einer Whitelist absichern.

Fazit

Die include- und require-Familie ist der Weg, wie PHP-Projekte DRY bleiben: Gemeinsames Markup, Konfiguration und Logik liegen in einzelnen Dateien und werden bei Bedarf in Seiten eingebunden. require/require_once verwenden, wenn eine Datei obligatorisch ist, include/include_once, wenn sie optional ist, Pfade immer mit __DIR__ verankern und niemals einen benutzergesteuerten Pfad einbinden. Als Nächstes siehe PHP Functions für die Organisation der wiederverwendbaren Logik, die man typischerweise in eingebundenen Dateien platziert.

Diagramm

graph TD;
A[PHP Page]-->B[Included File];

Übungen