include

L'instruction include en PHP

include intègre le contenu d'un autre fichier PHP dans le script courant et l'exécute à l'endroit où l'instruction apparaît. Conceptuellement, PHP copie le fichier inclus à la place, l'évalue dans la même portée, puis continue. C'est ainsi que vous évitez de répéter du code partagé — en-têtes, pieds de page, navigation, configuration et fonctions réutilisables — sur de nombreuses pages.

Cette page couvre la syntaxe, le fonctionnement de la portée, ce que include retourne, comment il diffère de require, et les erreurs courantes à éviter.

Syntaxe

include 'filename.php';

Le chemin peut être relatif ou absolu. include est une construction du langage, pas une fonction, donc les parenthèses sont facultatives — include 'file.php'; et include('file.php'); fonctionnent tous les deux.

Lorsque PHP exécute un include, il recherche le fichier dans cet ordre : le chemin donné (si relatif, résolu par rapport au répertoire de travail courant et au paramètre include_path), puis le répertoire du script en cours d'exécution. Pour rendre les inclusions robustes quel que soit l'endroit d'où le script d'entrée est appelé, ancrez-les au fichier courant :

include __DIR__ . '/partials/header.php';

__DIR__ est le répertoire du fichier contenant l'instruction, donc l'inclusion se résout correctement même lorsque le script est exécuté depuis un autre répertoire.

Un exemple concret

Comme include opère sur des fichiers séparés, la façon la plus claire de le voir en action est de créer ces fichiers à l'exécution. L'extrait ci-dessous écrit un petit partiel, l'inclut et affiche le résultat — il est entièrement exécutable en tant que script unique :

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

Le fichier inclus peut lire $name car include partage la portée environnante. C'est la chose la plus importante à comprendre sur include : ce n'est pas un système de modules isolé. Toutes les variables qui existent avant include sont disponibles dans le fichier inclus, et toutes les variables que le fichier inclus définit sont accessibles dans l'appelant.

Retourner une valeur depuis un fichier inclus

Un fichier inclus peut return une valeur, qui devient le résultat de l'expression include. C'est la manière idiomatique de charger une configuration :

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Si le fichier inclus ne fait pas de return, l'expression include vaut 1 en cas de succès.

include vs require (et les variantes _once)

PHP dispose de quatre instructions apparentées. Elles incluent toutes un fichier ; elles diffèrent par ce qui se passe en cas d'échec et si les inclusions en double sont ignorées.

Règles empiriques :

• Utilisez require pour les fichiers sans lesquels le script ne peut pas fonctionner (un fichier de configuration, une définition de classe, une connexion à la base de données). Échouer rapidement avec une erreur fatale est plus sûr que de continuer dans un état cassé.
• Utilisez include pour les éléments optionnels, comme un widget de barre latérale ou un bloc publicitaire, où un fichier manquant ne devrait pas faire tomber toute la page.
• Utilisez les variantes _once lorsque ré-inclure un fichier causerait des erreurs — le plus souvent lorsqu'il déclare des fonctions ou des classes, car les redéclarer est une erreur fatale.

Pièges courants

• Faire confiance aux données utilisateur dans un chemin. Ne passez jamais de données de requête non filtrées à include (par exemple include $_GET['page'] . '.php';). Cela ouvre la porte aux attaques par inclusion de fichiers locaux. Validez plutôt contre une liste autorisée de fichiers connus.
• Chemins relatifs qui échouent. Un simple include 'header.php'; dépend du répertoire de travail courant et peut échouer lorsque le script est invoqué depuis ailleurs. Préférez les chemins ancrés avec __DIR__.
• Redéclarer des fonctions ou des classes. Si un fichier qui définit des fonctions est inclus deux fois via un simple include, PHP lance une erreur fatale "Cannot redeclare". Utilisez include_once pour de tels fichiers.
• Supposer l'isolation. Comme la portée est partagée, un fichier inclus peut écraser vos variables. Gardez les inclusions ciblées et prévisibles.

Pourquoi utiliser include

• Réutilisabilité — définissez le code ou la mise en page partagés une seule fois et intégrez-les dans chaque page qui en a besoin.
• Maintenabilité — modifiez la navigation dans un partiel et toutes les pages sont mises à jour.
• Structure — divisez une grande application en petits fichiers ciblés plutôt qu'un monolithe.

Sujets connexes

• PHP require et require_once — les équivalents qui échouent strictement.
• PHP include_once — inclure un fichier au maximum une fois.
• Fonctions PHP — ce que vous placez généralement dans des fichiers partagés inclus.
• Gestion de fichiers PHP — lire et écrire des fichiers à l'exécution.

Pratique