include_once

Die PHP include_once-Anweisung

include_once bindet eine Datei während der Ausführung ein und wertet sie aus, aber nur, wenn diese Datei noch nicht in der aktuellen Anfrage eingebunden wurde. Wird dieselbe Datei erneut mit include_once angefordert, überspringt PHP sie stillschweigend. Das macht es zur sicheren Wahl für Dateien, die Funktionen, Klassen oder Konstanten definieren — eine solche Datei zweimal einzubinden würde sonst einen fatalen „cannot redeclare"-Fehler auslösen.

Diese Seite behandelt die Syntax, die Unterschiede zwischen include_once und include sowie require_once, den Rückgabewert und die häufigen Anwendungsfälle.

Syntax

include_once ist ein Sprachkonstrukt, daher sind Klammern optional:

include_once 'filename.php';
include_once('filename.php'); // also valid

PHP verfolgt die Datei anhand ihres aufgelösten realen Pfads. Daher werden include_once 'lib.php' und include_once './lib.php', die auf dieselbe Datei auf dem Datenträger zeigen, als dieselbe Einbindung behandelt — die zweite wird übersprungen.

Wie include_once entscheidet, ob es einbindet

Die Regel lautet: einmal pro Anfrage eingebunden. Das folgende Beispiel verwendet tempnam(), um zur Laufzeit eine echte Datei zu erstellen, eine Funktionsdefinition hineinzuschreiben und sie dann zweimal einzubinden. Eine Funktionsdefinition zweimal mit einfachem include einzubinden würde zu einem Absturz führen; include_once tut das nicht.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

Das zweite include_once tut nichts, da die Datei bereits geladen wurde, sodass greet() nie neu deklariert wird.

Rückgabewert

include_once gibt 1 bei einer erstmaligen Einbindung zurück (wenn die Datei kein explizites return enthält), und true, wenn die Datei bereits eingebunden wurde. Wenn die Datei nicht gefunden werden kann, gibt es eine Warnung aus und gibt false zurück (das Skript wird nicht gestoppt — dafür ist require_once zuständig).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

Eine Datei kann auch einen Wert zurückgeben, was für Konfigurationsdateien praktisch ist:

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once im Vergleich zu den anderen dreien

PHP hat vier Konstrukte zur Dateieinbindung. Sie unterscheiden sich in zwei Dimensionen — einmal oder jedes Mal und Warnung oder fataler Fehler bei fehlender Datei:

Verwende include_once, wenn die Datei optional ist, aber nicht zweimal geladen werden darf. Verwende require_once, wenn die Datei wesentlich ist (eine Klasse, ohne die dein Code nicht funktioniert) und nicht zweimal geladen werden darf.

Wann es verwendet werden sollte

• Funktions- und Klassenbibliotheken. Jede Datei, die eine Funktion, Klasse oder ein Interface deklariert, sollte mit include_once (oder require_once) geladen werden, damit ein Redeklarationsfehler ausgeschlossen ist, auch wenn mehrere Teile der App sie einbinden.
• Gemeinsame Header/Footer. Eine header.php, die einmal pro Seite gerendert werden soll.
• Konstanten und Konfiguration. Dateien, die mit define() Konstanten definieren — das Neudefinieren einer Konstante erzeugt eine Warnung.

In modernem PHP ersetzt Composers Autoloader in der Regel die manuelle Einbindung für Klassen, aber include_once ist nach wie vor überall in Legacy-Code, Templates und kleinen Skripten zu finden.

Häufige Stolpersteine

• Es schützt vor doppelter Einbindung, nicht vor Ladereihenfolge. include_once löst Abhängigkeiten zwischen Dateien nicht magisch auf; es verhindert nur, dass dieselbe Datei zweimal geladen wird.
• Die „once"-Prüfung gilt pro Anfrage, nicht dauerhaft — jede HTTP-Anfrage beginnt mit einem sauberen Zustand.
• Symlinks und verschiedene relative Pfade zur gleichen Datei werden durch den realen Pfad dedupliziert, aber eine Datei, die über zwei tatsächlich unterschiedliche Pfade erreichbar ist (z. B. verschiedene Einhängepunkte), kann zweimal eingebunden werden.

Fazit

include_once bindet eine Datei genau einmal pro Anfrage ein und verhindert fatale Redeklarationsfehler sowie doppelte Ausgabe. Greife darauf (oder auf require_once) zurück, wenn eine Datei Funktionen, Klassen oder Konstanten definiert. Wähle zwischen den include_*- und require_*-Varianten danach, ob eine fehlende Datei eine behebbare Warnung oder ein harter Abbruch sein soll.

Übung