require

Die PHP-Anweisung require

In PHP liest require den Inhalt einer anderen PHP-Datei, fügt ihn an der Stelle ein, an der require steht, und wertet ihn aus, als wäre er dort eingetippt worden. So teilen PHP-Projekte ihren Code auf mehrere Dateien auf: Konfiguration, Hilfsfunktionen, Klassendefinitionen und Templates leben jeweils in eigenen Dateien und werden mit require eingebunden.

Der entscheidende Unterschied zwischen require und seinem Geschwister include liegt darin, wie es auf eine fehlende Datei reagiert. Kann die Zieldatei nicht gefunden werden, stoppt require das Skript mit einem fatalen Fehler, während include nur eine Warnung ausgibt und weitermacht. Damit ist require die richtige Wahl für Dateien, ohne die das Skript nicht ausgeführt werden kann.

Diese Anleitung behandelt die Syntax, ausführbare Beispiele, den Unterschied zwischen require und include, wann require_once sinnvoll ist und welche Fallstricke es gibt.

Syntax

require ist ein Sprachkonstrukt und keine Funktion, daher kann es mit oder ohne Klammern geschrieben werden:

require '/path/to/file.php';
require('/path/to/file.php'); // also valid, but parentheses are unnecessary

In der Praxis sollen Pfade fast immer relativ zur aktuellen Skriptdatei sein und nicht zum Arbeitsverzeichnis von PHP. Die magische Konstante __DIR__ enthält das Verzeichnis der Datei, in der sie steht. Pfade daraus aufzubauen stellt sicher, dass require funktioniert, egal von wo das Skript aufgerufen wird:

require __DIR__ . '/config.php';

Ein ausführbares Beispiel

Das folgende Snippet erstellt eine kleine Hilfsdatei, bindet sie ein und ruft dann die darin definierte Funktion auf. Es kann in eine einzelne .php-Datei eingefügt und ausgeführt werden – die Hilfsdatei wird zur Laufzeit im selben Verzeichnis erstellt, sodass das Beispiel eigenständig ist.

<?php

// Create a helper file next to this script.
file_put_contents(__DIR__ . '/greet.php', <<<'PHP'
<?php
function greet($name) {
    return "Hello, $name!";
}
PHP);

// Pull the helper in. After this line greet() is available.
require __DIR__ . '/greet.php';

echo greet('Ada'); // Hello, Ada!

Ausgabe:

Hello, Ada!

Sobald eine Datei eingebunden wurde, wird alles, was sie deklariert – Funktionen, Klassen und alle top-level-Variablen – Teil des aktuellen Gültigkeitsbereichs, genau so, als wäre es inline geschrieben worden.

require vs include

Beide Anweisungen laden und werten eine Datei aus. Der einzige verhaltensbedingte Unterschied liegt darin, was passiert, wenn die Datei fehlt oder nicht lesbar ist:

Verwende require für Dinge wie eine Datenbankverbindungsdatei oder einen Autoloader, bei denen ein Weiterlaufen ohne sie keinen Sinn ergibt. Greife nur auf include zurück, wenn eine fehlende Datei toleriert werden soll – zum Beispiel bei einem optionalen Theme-Override.

require_once: Doppeltes Laden vermeiden

Dieselbe Datei zweimal einzubinden verursacht Probleme: Das erneute Deklarieren einer Funktion oder Klasse ist selbst ein fataler Fehler. require_once löst das, indem es sich merkt, welche Dateien bereits geladen wurden, und doppelte Anfragen überspringt.

<?php
require_once __DIR__ . '/User.php'; // loads the file
require_once __DIR__ . '/User.php'; // already loaded — does nothing

Als Faustregel gilt: require_once für Dateien verwenden, die Dinge definieren (Klassen, Funktionsbibliotheken), und einfaches require für Dateien, die absichtlich mehrfach ausgeführt werden sollen, etwa ein Template, das in einer Schleife gerendert wird. Die gleiche once/non-once-Unterscheidung gilt für include als include_once.

Häufige Muster

Eine gemeinsame Konfigurationsdatei, die am Anfang eines Einstiegsskripts geladen wird:

<?php
require __DIR__ . '/config.php';

// $dbHost, $dbUser, etc. defined in config.php are now available.
$pdo = new PDO("mysql:host=$dbHost", $dbUser, $dbPass);

Eine eingebundene Datei kann auch einen Wert returnen, zu dem require ausgewertet wird. Das ist eine saubere Möglichkeit, ein Konfigurations-Array zu laden:

// config.php
<?php
return [
    'host' => 'localhost',
    'port' => 3306,
];

// index.php
<?php
$config = require __DIR__ . '/config.php';
echo $config['port']; // 3306

Fallstricke

• Pfade aus __DIR__ aufbauen, nicht aus relativen Strings. require 'config.php' wird relativ zum aktuellen Arbeitsverzeichnis von PHP aufgelöst, das vom Skriptort abweichen kann und unter verschiedenen Webservern oder CLI-Aufrufen stillschweigend fehlschlägt.
• require wird an der Stelle ausgeführt, an der es steht. Es innerhalb einer Funktion zu platzieren (wie im obigen Beispiel) verschiebt das Laden bis zum Aufruf dieser Funktion und begrenzt alle top-level-Variablen der Datei auf den Gültigkeitsbereich dieser Funktion.
• Für Klassen einen Autoloader bevorzugen. Dutzende von Klassendateien manuell einzubinden ist fehleranfällig. Moderne Projekte verwenden vendor/autoload.php von Composer (einmalig mit require geladen) und lassen PSR-4-Autoloading Klassen bei Bedarf einbinden.

Fazit

require ist die Grundlage der Code-Organisation in PHP: Es teilt ein Programm in fokussierte Dateien auf und lädt die, von denen ein Skript abhängt, und schlägt laut fehl, wenn eine fehlt. Pfade aus __DIR__ aufbauen, require_once für Definitionen wählen, um doppeltes Laden zu vermeiden, und include nur dann einsetzen, wenn eine fehlende Datei akzeptabel ist. Für Klassenbibliotheken ist ein Composer-Autoloader der moderne Ersatz für handgeschriebene require-Listen.

Übungen