PHP include und require: andere PHP-Dateien einbinden

include 'header.php'; führt an dieser Stelle im Skript den Code einer anderen PHP-Datei aus, als wäre er dort eingefügt. require 'header.php'; macht dasselbe, aber wenn sich die Datei nicht laden lässt, stoppt require das Skript mit einem fatalen Fehler, während include nur eine Warnung ausgibt und weitermacht. Der übliche erste Einsatz ist ein Header und ein Footer, die sich alle Seiten teilen.

Der Block schreibt zuerst header.php und footer.php, damit es Dateien zum Einbinden gibt. Führe ihn aus und schau dir den Tab Page an:

<?php
file_put_contents('header.php', <<<'PHP'
<!doctype html>
<html>
<head><title><?= $title ?></title></head>
<body style="font-family: sans-serif">
<nav><a href="?">Home</a> | <a href="?">Shop</a> | <a href="?">Contact</a></nav>
<hr>
PHP);

file_put_contents('footer.php', <<<'PHP'
<hr>
<footer>&copy; <?= date('Y') ?> My Shop</footer>
</body>
</html>
PHP);

$title = 'Welcome';
require 'header.php';
?>
<h1><?= $title ?></h1>
<p>This page is made of three files: header.php, this script, and footer.php.</p>
<?php
require 'footer.php';

Die eingebundenen Dateien sind gewöhnliche PHP-Dateien: Sie können HTML mit <?= ?>-Tags enthalten und sehen die Variable $title, die vor dem require gesetzt wurde. Ändere den Titel und führe den Code erneut aus; jede Seite, die den Header einbindet, würde eine Änderung an dieser einen Datei übernehmen.

include vs require

Der einzige Unterschied ist, was passiert, wenn die Datei fehlt oder nicht lesbar ist. include gibt zwei Warnungen aus, ergibt false, und das Skript läuft weiter:

Warning: include(sidebar.php): Failed to open stream: No such file or directory in /home/index.php on line 2

Warning: include(): Failed opening 'sidebar.php' for inclusion (include_path='.:/usr/share/php83') in /home/index.php on line 2

require gibt dieselbe Warnung aus und wirft dann einen Error, der das Skript beendet, außer etwas fängt ihn ab:

PHP Warning:  require(config.php): Failed to open stream: No such file or directory in /home/index.php on line 2
PHP Fatal error:  Uncaught Error: Failed opening required 'config.php' (include_path='.:/usr/share/php83') in /home/index.php:2

Verwende also require für alles, ohne das die Seite nicht laufen kann (Konfiguration, Funktionsbibliotheken, Klassendateien), und include für optionale Teile. Für einen Teil, der berechtigterweise fehlen kann, prüfst du vorher, statt dich auf die Warnung zu verlassen:

<?php
file_put_contents('banner.php', '<?php echo "Spring sale: 20% off\n";');

foreach (['banner.php', 'sidebar.php'] as $part) {
    if (is_file($part)) {
        $result = include $part;
        echo "$part included, include returned ";
        var_dump($result);
    } else {
        echo "$part not found, skipped\n";
    }
}

Ausgabe:

Spring sale: 20% off
banner.php included, include returned int(1)
sidebar.php not found, skipped

include_once und require_once

Eine Datei, die eine Funktion oder eine Klasse definiert, lässt sich nur einmal laden: Sie ein zweites Mal zu laden ist ein fataler Fehler, weil die Funktion schon existiert.

Fatal error: Cannot redeclare greet() (previously declared in /home/helpers.php:2) in /home/helpers.php on line 2

Das passiert, sobald zwei Dateien jeweils require 'helpers.php' aufrufen. require_once und include_once merken sich, welche Dateien schon geladen wurden, überspringen sie beim zweiten Mal und liefern true:

<?php
file_put_contents('helpers.php', <<<'PHP'
<?php
function greet(string $name): string
{
    return "Hello, $name";
}
PHP);

var_dump(require_once 'helpers.php');   // loaded: 1
var_dump(require_once 'helpers.php');   // already loaded: true, skipped
var_dump(include_once 'helpers.php');   // the same list for both

echo greet('Ada'), "\n";

Ausgabe:

int(1)
bool(true)
bool(true)
Hello, Ada

Verwende die _once-Formen für Dateien, die etwas deklarieren, und einfaches include für Templates, die du mehr als einmal ausgeben willst. In Projekten mit Composer lädt der Autoloader Klassendateien für dich, also verschwinden require_once-Aufrufe für Klassen größtenteils; siehe Composer.

Einen Wert aus einer eingebundenen Datei zurückgeben

Ein return auf oberster Ebene einer eingebundenen Datei beendet diese Datei und gibt einen Wert an den Ausdruck mit include oder require zurück. Das ergibt eine saubere Konfigurationsdatei: keine globalen Variablen, nur ein Wert, den du einem beliebigen Namen zuweist.

<?php
file_put_contents('config.php', <<<'PHP'
<?php
return [
    'site'     => 'My Shop',
    'currency' => 'EUR',
    'debug'    => false,
    'db'       => ['host' => 'localhost', 'name' => 'shop'],
];
PHP);

$config = require 'config.php';

echo $config['site'], "\n";
echo $config['db']['name'], "\n";
var_dump($config['debug']);

Ausgabe:

My Shop
shop
bool(false)

Die Konfigurationsdateien von Laravel (config/app.php, config/database.php und die übrigen) funktionieren so.

Variablen und Scope in eingebundenen Dateien

Eingebundener Code läuft im Scope der Zeile, die ihn einbindet. Am Anfang eines Skripts sieht er jede globale Variable; in einer Funktion sieht er nur die lokalen Variablen dieser Funktion. Mit der zweiten Regel funktioniert ein winziger Template-Renderer: eine Funktion, deren lokale Variablen genau die Variablen sind, die das Template sehen soll.

<?php
file_put_contents('product-list.php', <<<'PHP'
<h2><?= htmlspecialchars($heading) ?></h2>
<ul>
<?php foreach ($products as $name => $price): ?>
    <li><?= htmlspecialchars($name) ?>: <?= number_format($price, 2) ?> EUR</li>
<?php endforeach; ?>
</ul>
<p><?= count($products) ?> products</p>
PHP);

function render(string $template, array $vars): string
{
    extract($vars);       // $vars['heading'] becomes $heading
    ob_start();           // capture the output instead of printing it
    include $template;
    return ob_get_clean();
}

$secret = 'not visible inside the template';

echo render('product-list.php', [
    'heading'  => 'Fruit',
    'products' => ['Apple' => 0.5, 'Mango' => 1.75, 'Cherries' => 4.2],
]);
echo render('product-list.php', [
    'heading'  => 'Tea',
    'products' => ['Sencha' => 6, 'Earl Grey' => 4.5],
]);

Der Tab Page zeigt beide Listen, gerendert aus einer Template-Datei. Weil include in render() läuft, sieht das Template $heading und $products, aber nicht $secret. Die Form foreach ... endforeach im Template ist die alternative Syntax, die PHP für HTML-Templates anbietet.

Include-Pfade und DIR

Ein Pfad wie 'helper.php' wird nicht relativ zu der Datei aufgelöst, die das include enthält. PHP durchsucht die Einstellung include_path (die normalerweise mit . beginnt, dem aktuellen Arbeitsverzeichnis) und erst danach den eigenen Ordner der einbindenden Datei. In partials/nav.php kann include 'helper.php' also eine ganz andere helper.php aus dem Projektstamm laden. __DIR__, das Verzeichnis der aktuellen Datei, nimmt das Raten weg:

<?php
mkdir('partials');
file_put_contents('helper.php', '<?php echo "loaded the root helper.php\n";');
file_put_contents('partials/helper.php', '<?php echo "loaded partials/helper.php\n";');

file_put_contents('partials/nav.php', <<<'PHP'
<?php
include 'helper.php';                 // searched from the working directory
include __DIR__ . '/helper.php';      // always the file next to nav.php
echo "__DIR__ in nav.php is ", basename(__DIR__), "\n";
PHP);

include 'partials/nav.php';

Ausgabe:

loaded the root helper.php
loaded partials/helper.php
__DIR__ in nav.php is partials

Schreib jedes Include als __DIR__ . '/relative/path.php'. Das Arbeitsverzeichnis hängt davon ab, wie das Skript gestartet wurde (der Webserver, ein Cronjob, die Kommandozeile aus einem anderen Ordner), aber __DIR__ ändert sich nie.

Nie eine Datei einbinden, die der Nutzer benennt

Ein häufiger erster Router liest den Seitennamen aus der URL: include $_GET['page'] . '.php';. Damit wählt ein Besucher, welche Datei auf dem Server läuft, zum Beispiel ?page=../../config (Local File Inclusion), und mit alten Einstellungen sogar eine Datei von einem anderen Server. Ordne erlaubte Namen stattdessen Dateien zu. Führe den Block aus und klicke auf die Links: Jeder Klick führt das Skript erneut mit einem anderen $_GET['page'] aus.

<?php
file_put_contents('home.php', '<h2>Home</h2><p>Welcome to the shop.</p>');
file_put_contents('about.php', '<h2>About</h2><p>We sell fruit since 1999.</p>');
file_put_contents('contact.php', '<h2>Contact</h2><p>hello@example.com</p>');

$pages = [
    'home'    => 'home.php',
    'about'   => 'about.php',
    'contact' => 'contact.php',
];

$page = $_GET['page'] ?? 'home';
$file = $pages[$page] ?? null;
if ($file === null) {
    http_response_code(404);   // before any output, or the header cannot be sent
}
?>
<nav>
    <a href="?page=home">Home</a> |
    <a href="?page=about">About</a> |
    <a href="?page=contact">Contact</a> |
    <a href="?page=../secret">../secret</a>
</nav>
<?php
if ($file === null) {
    echo '<h2>Not found</h2><p>No page called ', htmlspecialchars($page), '.</p>';
} else {
    require __DIR__ . '/' . $file;
}

Nur die drei Namen in $pages können je require erreichen; der Link ../secret bekommt die Seite „Not found“. Wie du Request-Werte sicher liest, steht unter $_GET und$_POST.