PHP include et require : charger d'autres fichiers PHP

include 'header.php'; exécute le code d'un autre fichier PHP à cet endroit du script, comme s'il y était collé. require 'header.php'; fait la même chose, mais si le fichier ne peut pas être chargé, require arrête le script avec une erreur fatale alors qu'include affiche seulement un warning et continue. Le premier usage habituel est un en-tête et un pied de page partagés par toutes les pages.

Le bloc écrit d'abord header.php et footer.php, pour qu'il y ait des fichiers à inclure. Exécutez-le et regardez l'onglet Page :

<?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';

Les fichiers inclus sont des fichiers PHP ordinaires : ils peuvent contenir du HTML avec des balises <?= ?>, et ils voient la variable $title définie avant le require. Modifiez le titre et relancez ; chaque page qui requiert l'en-tête prendrait en compte une modification de ce seul fichier.

include ou require

La seule différence est ce qui se passe quand le fichier manque ou est illisible. include affiche deux warnings, vaut false, et le script continue :

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 affiche le même warning puis lève une Error, qui termine le script sauf si quelque chose l'intercepte :

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

Utilisez donc require pour tout ce sans quoi la page ne peut pas s'exécuter (configuration, bibliothèques de fonctions, fichiers de classes) et include pour les parties facultatives. Pour une partie qui peut légitimement manquer, vérifiez-la d'abord au lieu de compter sur le warning :

<?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";
    }
}

Sortie :

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

include_once et require_once

Un fichier qui définit une fonction ou une classe ne peut être chargé qu'une fois : le charger une seconde fois est une erreur fatale, car la fonction existe déjà.

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

Cela arrive dès que deux fichiers font chacun require 'helpers.php'. require_once et include_once se souviennent des fichiers déjà chargés et les sautent la seconde fois, en renvoyant 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";

Sortie :

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

Utilisez les formes _once pour les fichiers qui déclarent des choses, et un simple include pour les templates que vous voulez afficher plus d'une fois. Dans les projets qui utilisent Composer, l'autoloader charge les fichiers de classes pour vous, donc les appels require_once pour les classes disparaissent en grande partie ; voir Composer.

Renvoyer une valeur depuis un fichier inclus

Un return au niveau principal d'un fichier inclus arrête ce fichier et rend une valeur à l'expression include ou require. Cela donne un fichier de configuration propre : pas de variables globales, juste une valeur que vous affectez au nom de votre choix.

<?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']);

Sortie :

My Shop
shop
bool(false)

Les fichiers de configuration de Laravel (config/app.php, config/database.php et les autres) fonctionnent ainsi.

Variables et portée dans les fichiers inclus

Le code inclus s'exécute dans la portée de la ligne qui l'inclut. En haut d'un script, il voit toutes les variables globales ; dans une fonction, il ne voit que les variables locales de cette fonction. Cette seconde règle est le principe d'un petit moteur de templates : une fonction dont les variables locales sont exactement celles que le template doit voir.

<?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],
]);

L'onglet Page affiche les deux listes, rendues à partir d'un seul fichier de template. Comme include s'exécute dans render(), le template voit $heading et $products mais pas $secret. La forme foreach ... endforeach utilisée dans le template est la syntaxe alternative que PHP propose pour les templates HTML.

Chemins d'inclusion et DIR

Un chemin comme 'helper.php' n'est pas résolu par rapport au fichier qui contient l'include. PHP cherche dans le réglage include_path (qui commence normalement par ., le dossier de travail courant) et seulement ensuite dans le dossier du fichier qui inclut. Donc dans partials/nav.php, include 'helper.php' peut charger un helper.php complètement différent situé à la racine du projet. __DIR__, le dossier du fichier courant, supprime toute incertitude :

<?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';

Sortie :

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

Écrivez chaque include sous la forme __DIR__ . '/relative/path.php'. Le dossier de travail dépend de la façon dont le script a été lancé (le serveur web, une tâche cron, la ligne de commande depuis un autre dossier), mais __DIR__ ne change jamais.

Ne jamais inclure un fichier nommé par l'utilisateur

Un premier routeur courant lit le nom de la page dans l'URL : include $_GET['page'] . '.php';. Cela permet à un visiteur de choisir quel fichier du serveur s'exécute, par exemple ?page=../../config (inclusion de fichier local), et avec d'anciens réglages même un fichier d'un autre serveur. Associez plutôt des noms autorisés à des fichiers. Exécutez le bloc et cliquez sur les liens : chaque clic relance le script avec un $_GET['page'] différent.

<?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;
}

Seuls les trois noms de $pages peuvent atteindre require ; le lien ../secret obtient la page « Not found ». La lecture sûre des valeurs de requête est expliquée dans $_GET et$_POST.