include_once

L'instruction PHP include_once

include_once inclut et évalue un fichier lors de l'exécution, mais uniquement si ce fichier n'a pas déjà été inclus dans la requête en cours. Si le même fichier est demandé à nouveau avec include_once, PHP l'ignore silencieusement. C'est donc le choix sûr pour les fichiers qui définissent des fonctions, des classes ou des constantes — inclure un tel fichier deux fois provoquerait sinon une erreur fatale « cannot redeclare ».

Cette page couvre la syntaxe, les différences entre include_once et include ou require_once, la valeur de retour, et les cas courants où on l'utilise vraiment.

Syntaxe

include_once est une construction du langage, les parenthèses sont donc optionnelles :

include_once 'filename.php';
include_once('filename.php'); // also valid

PHP identifie le fichier par son chemin réel résolu. Ainsi, include_once 'lib.php' et include_once './lib.php' qui pointent vers le même fichier sur disque sont traités comme la même inclusion — la seconde est ignorée.

Comment include_once décide d'inclure ou non

La règle est une inclusion par requête. L'exemple ci-dessous utilise tempnam() pour créer un fichier réel à l'exécution, y écrire une définition de fonction, puis l'inclure deux fois. Inclure une définition de fonction deux fois avec un simple include provoquerait un crash ; include_once ne le fait pas.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

Le second include_once ne fait rien car le fichier a déjà été chargé, donc greet() n'est jamais redéclarée.

Valeur de retour

include_once retourne 1 lors d'une première inclusion (quand le fichier n'a pas de return explicite), et true si le fichier a déjà été inclus. Si le fichier est introuvable, il émet un avertissement et retourne false (il n'arrête pas le script — c'est le rôle de require_once).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

Un fichier peut également retourner une valeur, ce qui est pratique pour les fichiers de configuration :

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once face aux trois autres

PHP dispose de quatre constructions d'inclusion de fichiers. Elles diffèrent sur deux axes — une fois ou à chaque fois et avertissement ou erreur fatale si le fichier est manquant :

Utilisez include_once quand le fichier est optionnel mais ne doit pas être chargé deux fois. Utilisez require_once quand le fichier est essentiel (une classe sans laquelle votre code ne peut pas fonctionner) et ne doit pas être chargé deux fois.

Quand l'utiliser

• Bibliothèques de fonctions et de classes. Tout fichier qui déclare une fonction, une classe ou une interface doit être chargé avec include_once (ou require_once) pour qu'une erreur de redéclaration soit impossible, même si plusieurs parties de votre application l'importent.
• En-têtes et pieds de page partagés. Un header.php qui ne doit s'afficher qu'une fois par page.
• Constantes et configuration. Les fichiers qui utilisent define() pour déclarer des constantes — redéfinir une constante génère un avertissement.

En PHP moderne, l'autoloader de Composer remplace généralement les inclusions manuelles pour les classes, mais include_once est encore très présent dans le code legacy, les templates et les petits scripts.

Pièges courants

• Il protège contre la double inclusion, pas l'ordre de chargement. include_once ne résout pas magiquement les dépendances entre fichiers ; il empêche seulement le même fichier d'être chargé deux fois.
• La vérification « once » est par requête, non persistante — chaque requête HTTP repart d'un état vierge.
• Les liens symboliques et différents chemins relatifs vers le même fichier sont dédupliqués par chemin réel, mais un fichier accessible via deux chemins réellement différents (par exemple des montages différents) peut être inclus deux fois.

Conclusion

include_once inclut un fichier exactement une fois par requête, évitant ainsi les erreurs fatales de redéclaration et les sorties dupliquées. Utilisez-le (ou require_once) chaque fois qu'un fichier définit des fonctions, des classes ou des constantes. Choisissez entre les familles include_* et require_* selon qu'un fichier manquant doit constituer un avertissement récupérable ou un arrêt définitif.

Pratique