require_once

Le mot-clé PHP require_once

require_once inclut et évalue un fichier PHP externe à l'endroit où l'instruction est écrite — mais uniquement la première fois que ce fichier est demandé. Si le même fichier est demandé à nouveau plus tard dans la même requête, PHP l'ignore. Cela fait de require_once la façon la plus sûre d'inclure des fichiers qui définissent des fonctions, des classes, des traits ou des constantes, car les charger une seconde fois provoquerait une erreur fatale du script.

Cette page couvre la syntaxe, le fonctionnement de la garantie « une seule fois », des exemples exécutables et les différences entre require_once, require, include et include_once.

Syntaxe

Le mot-clé require_once inclut et évalue un fichier PHP externe en s'assurant qu'il n'est traité qu'une seule fois. Voici la syntaxe de base :

La syntaxe PHP de require_once

require_once 'path/to/file.php';

Cela inclut et évalue le contenu de path/to/file.php, mais uniquement s'il n'a pas déjà été inclus au cours de cette requête. Comme il s'agit d'un construct du langage (et non d'une fonction), les parenthèses sont facultatives — require_once 'file.php'; et require_once('file.php'); se comportent de la même manière.

Remarque : si le fichier spécifié est introuvable, require_once déclenche une erreur fatale et arrête le script. Son équivalent include_once n'émet qu'un avertissement et laisse le script continuer.

Fonctionnement de la garantie « une seule fois »

PHP maintient une liste interne des fichiers qu'il a déjà chargés (résolus en chemins absolus). Lorsqu'il rencontre un require_once, il vérifie d'abord cette liste :

• Si le fichier n'est pas dans la liste, PHP le charge et l'exécute, puis l'ajoute à la liste.
• Si le fichier est déjà dans la liste, PHP ne fait rien et continue.

C'est ce qui rend require_once sûr pour les fichiers qui définissent des éléments. Les deux fichiers suivants l'illustrent. helpers.php définit une fonction et affiche une ligne pour voir à quel moment il est réellement exécuté :

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

L'exécution de main.php affiche :

helpers.php is being loaded
Hello, World!

La ligne "helpers.php is being loaded" n'apparaît qu'une seule fois, même si le fichier a été demandé deux fois — et la deuxième demande n'a pas redéclaré greet(), ce qui aurait sinon provoqué une erreur fatale.

Exemples

Voyons quelques exemples pratiques d'utilisation du mot-clé require_once :

Exemples de require_once en PHP

<?php

// Example 1
require_once 'config.php';

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

Ces deux exemples incluent et évaluent des fichiers externes exactement une fois. Cela évite les erreurs qui surviennent lorsqu'un fichier est chargé deux fois — le plus souvent la redéclaration d'une fonction ou d'une classe.

Remarque : bien que require_once puisse être placé dans une fonction, le suivi des inclusions par PHP est global pour toute la requête. Le placement au niveau supérieur est généralement préféré ; recourez à l'inclusion dans une fonction uniquement lorsque le chargement doit être conditionnel.

require_once vs les autres mots-clés d'inclusion

PHP dispose de quatre constructs d'inclusion. Ils diffèrent sur deux axes indépendants : ce qui se passe en cas d'échec, et si le fichier peut être chargé plusieurs fois.

Les variantes _once existent précisément pour éviter de réexécuter un fichier. Avec un simple require, demander helpers.php deux fois l'exécute deux fois — et la deuxième exécution échoue fatalement en tentant de redéclarer greet() :

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

Règle générale : utilisez require_once pour les fichiers qui définissent des éléments (bibliothèques de fonctions, classes, configuration ne devant pas s'exécuter deux fois) ; utilisez include pour les fichiers qui ne font que produire une sortie, comme un en-tête de page réutilisable que vous souhaitez afficher plusieurs fois intentionnellement.

Avantages

L'utilisation du mot-clé require_once présente plusieurs avantages, notamment :

• Prévention des erreurs : garantit qu'un fichier n'est traité qu'une seule fois, évitant les erreurs fatales liées à la redéclaration de fonctions, classes ou traits.
• Utilisation efficace des ressources : empêche le chargement et l'analyse redondants des fichiers. (Remarque : PHP maintient un léger surcoût de suivi pour les fichiers inclus, mais celui-ci est généralement compensé par le coût de la réanalyse de fichiers volumineux.)

Conclusion

En conclusion, require_once est un outil fiable pour inclure des fichiers PHP externes tout en évitant les traitements en double et les erreurs fatales. Utilisez-le lorsqu'un fichier doit être chargé exactement une fois, et choisissez require ou include lorsque vous avez besoin d'une gestion des erreurs différente ou souhaitez éviter le surcoût de suivi. Nous espérons que ce guide vous aidera à écrire du code PHP plus robuste.

Pratique