require_once

Das PHP-Schlüsselwort require_once

require_once bindet eine externe PHP-Datei an der Stelle ein und wertet sie aus, an der die Anweisung steht — aber nur beim ersten Mal, wenn diese Datei angefordert wird. Wird dieselbe Datei später innerhalb derselben Anfrage erneut angefordert, überspringt PHP sie. Damit ist require_once die sicherste Methode, um Dateien einzubinden, die Funktionen, Klassen, Traits oder Konstanten definieren, da ein zweites Laden dieser Definitionen das Skript zum Absturz bringen würde.

Diese Seite behandelt die Syntax, wie die „Einmal"-Garantie funktioniert, ausführbare Beispiele sowie die Unterschiede zwischen require_once, require, include und include_once.

Syntax

Das Schlüsselwort require_once bindet eine externe PHP-Datei ein und wertet sie aus, wobei sichergestellt wird, dass sie nur einmal verarbeitet wird. Die grundlegende Syntax lautet:

Die PHP-Syntax von require_once

require_once 'path/to/file.php';

Dies bindet den Inhalt von path/to/file.php ein und wertet ihn aus, aber nur, wenn er während dieser Anfrage noch nicht eingebunden wurde. Da es sich um ein Sprachkonstrukt (keine Funktion) handelt, sind die Klammern optional — require_once 'file.php'; und require_once('file.php'); verhalten sich gleich.

Hinweis: Wenn die angegebene Datei nicht gefunden werden kann, löst require_once einen schwerwiegenden Fehler aus und stoppt das Skript. Das Gegenstück include_once gibt lediglich eine Warnung aus und lässt das Skript weiterlaufen.

Wie die „Nur einmal"-Garantie funktioniert

PHP führt intern eine Liste der bereits geladenen Dateien (aufgelöst zu ihren absoluten Pfaden). Wenn es auf ein require_once trifft, prüft es zunächst diese Liste:

• Wenn die Datei nicht auf der Liste steht, lädt und führt PHP sie aus und fügt sie dann zur Liste hinzu.
• Wenn die Datei bereits auf der Liste steht, tut PHP nichts und fährt fort.

Das macht require_once sicher für Dateien, die Definitionen enthalten. Die folgenden zwei Dateien veranschaulichen dies. helpers.php definiert eine Funktion und gibt eine Zeile aus, damit wir sehen können, wann sie tatsächlich ausgeführt wird:

<?php
// helpers.php
echo "helpers.php is being loaded\n";

function greet($name)
{
    return "Hello, $name!";
}

<?php
// main.php
require_once 'helpers.php';
require_once 'helpers.php'; // second request is silently skipped

echo greet("World") . "\n";

Das Ausführen von main.php gibt Folgendes aus:

helpers.php is being loaded
Hello, World!

Die Zeile "helpers.php is being loaded" erscheint nur einmal, obwohl die Datei zweimal angefordert wurde — und die zweite Anforderung hat greet() nicht erneut deklariert, was andernfalls ein schwerwiegender Fehler gewesen wäre.

Beispiele

Schauen wir uns einige praktische Beispiele an, wie das Schlüsselwort require_once verwendet werden kann:

Beispiele für PHP require_once

<?php

// Example 1
require_once 'config.php';

// Example 2
function myFunction()
{
  require_once 'helpers.php';
  // Code block here
}

Beide Beispiele binden externe Dateien genau einmal ein und werten sie aus. Dies verhindert die Fehler, die auftreten, wenn eine Datei zweimal geladen wird — am häufigsten das erneute Deklarieren einer Funktion oder einer Klasse.

Hinweis: Obwohl require_once innerhalb einer Funktion platziert werden kann, ist das Einbindungs-Tracking von PHP global für die gesamte Anfrage. Platzierung auf oberster Ebene wird in der Regel bevorzugt; verwenden Sie die Einbindung innerhalb von Funktionen nur, wenn das Laden bedingt erfolgen muss.

require_once im Vergleich zu den anderen Einbindungs-Schlüsselwörtern

PHP verfügt über vier Einbindungskonstrukte. Sie unterscheiden sich in zwei unabhängigen Dimensionen: was bei einem Fehler passiert und ob die Datei mehr als einmal geladen werden kann.

Die _once-Varianten existieren genau dafür, um ein erneutes Ausführen einer Datei zu vermeiden. Mit dem einfachen require führt das zweimalige Anfordern von helpers.php dazu, dass es zweimal ausgeführt wird — und der zweite Aufruf schlägt fatal fehl, da er versucht, greet() erneut zu deklarieren:

PHP Fatal error: Cannot redeclare function greet() ...

Faustregel: Verwenden Sie require_once für Dateien, die Dinge definieren (Funktionsbibliotheken, Klassen, Konfigurationen, die nicht zweimal ausgeführt werden dürfen); verwenden Sie include für Dateien, die nur Ausgaben erzeugen, wie z. B. einen wiederverwendbaren Seitenkopf, den Sie absichtlich mehrfach rendern.

Vorteile

Die Verwendung des Schlüsselworts require_once hat mehrere Vorteile, darunter:

• Fehler verhindern: Stellt sicher, dass eine Datei nur einmal verarbeitet wird, und vermeidet schwerwiegende Fehler durch erneutes Deklarieren von Funktionen, Klassen oder Traits.
• Effizienter Ressourceneinsatz: Verhindert redundantes Laden und Parsen von Dateien. (Hinweis: PHP pflegt einen kleinen Tracking-Overhead für eingebundene Dateien, der jedoch in der Regel durch die Kosten des erneuten Parsens großer Dateien aufgewogen wird.)

Fazit

Zusammenfassend lässt sich sagen, dass require_once ein zuverlässiges Werkzeug zum Einbinden externer PHP-Dateien ist, das doppelte Verarbeitung und schwerwiegende Fehler verhindert. Verwenden Sie es, wenn eine Datei genau einmal geladen werden muss, und wählen Sie require oder include, wenn Sie eine andere Fehlerbehandlung benötigen oder den Tracking-Overhead vermeiden möchten. Wir hoffen, dass dieser Leitfaden Ihnen hilft, robusteren PHP-Code zu schreiben.

Übungen