19.3 require, require_once, include, include_once

Il existe différentes instructions pour inclure des fichiers dans un script PHP : require, require_once, include, include_once.

Cet article vous présente les différences entre ces quatre instructions.

require vs include

À prime abord, on remarque qu'il y a deux familles parmi ces quatre instructions : la famille require et la famille include. Les deux permettent d'effectuer la même tâche : inclure un fichier. Ce n'est que dans le cas où le fichier ne peut pas être inclus que le traitement sera différent.

Avec la famille require, que ce soit require ou require_once, si le fichier ne peut pas être inclus, une erreur fatale de niveau E_COMPILE_ERROR sera produite, ce qui mettra fin au script PHP.

Avec la famille include, que ce soit include ou include_once, si le ficher ne peut pas être inclus, PHP ne générera qu'une alerte de niveau E_WARNING. Le script PHP pourra donc continuer.

Donc, on utilisera la famille require lorsque la page Web a absolument besoin du fichier à inclure pour fonctionner. Dans les autres cas, on pourra utiliser la famille include.

Notez qu'il n'est pas utile de placer un require ou un include dans un try...catch puisqu'un fichier manquant ne lève pas d'exception alors l'erreur fatale ou l'avertissement sera tout de même généré.

Dans le reste de cet article, la différence entre une instruction et sa version se terminant par _once est illustrée avec la famille require. Les mêmes concepts sont applicables dans la famille include.

require

L'instruction require ajoute le fichier sans vérifier s'il a déjà été ajouté. Le même fichier pourrait donc être ajouté plus d'une fois si tel était le besoin. 

On utilisera généralement require avec les fichiers portant l'extension .inc., qui contiennent des extraits de pages Web.

Ex :

Remarquez qu'on utilise une barre oblique (/) et non une barre oblique inverse (\). Ceci assure que l'instruction fonctionnera correctement peu importe le système d'exploitation sur lequel le serveur est installé.

Si vous utilisez une barre oblique inverse, le code ne fonctionnera que sous Windows.

Il faut spécifier un chemin physique et non un URL. Le chemin ne doit pas débuter par une barre oblique sinon, le serveur le recherchera à la racine du disque.

require_once

L'instruction require_once, quant à elle, sera utilisée pour ajouter un fichier contenant des fonctions. Comme son nom l'indique, elle assure que si le fichier a déjà été ajouté, il ne sera pas ajouté une deuxième fois.

require_once permet donc d'ajouter une bibliothèque de fonction :

• dans une page Web

  et/ou

• dans les fichiers d'en-tête et de pied de page

et ce, sans que les fonctions contenues dans la bibliothèque soient définies deux fois.

On utilisera généralement require_once avec les bibliothèques, c'est-à-dire les fichiers .php dans lesquels des fonctions sont définies.

Ex :

Exemple concret

Voici un scénario classique où un même fichier .php risquerait d'être inclus plusieurs fois si on utilisait require plutôt que require_once :

• Dans le fichier entete.inc, on a besoin d'utiliser une fonction de notre bibliothèque de fonctions. Ce fichier débutera donc par une instruction qui permet d'inclure cette bibliothèque.
• Le fichier index.php a lui aussi besoin d'utiliser une fonction de notre bibliothèque. Il commence par inclure la bibliothèque puis, comme il souhaite utiliser toutes les balises communes d'en-tête, il inclus également entete.inc. Ceci cause une double inclusion de notre bibliothèque de fonctions.

C'est pourquoi les bibliothèques, dont l'extensions est généralement .php, seront incluses à l'aide de l'instruction require_once. On pourra donc les inclure dans chaque fichier qui doit les utiliser sans avoir à vérifier manuellement dans les autres fichiers inclus pour savoir si la bibliothèque en fait déjà partie.

Illustrons cet exemple

Problème avec require

Soit le fichier index.php qui a besoin d'utiliser une fonction déclarée dans notre bibliothèque. Dans le site Web de cet exemple, le fichier entete.inc a lui aussi besoin d'utiliser cette fonction. Chacun s'occupera donc d'inclure ma-bibliotheque.php.

Le problème, c'est que lors de l'exécution du code, PHP fera un « copier-coller virtuel », c'est-à-dire que ce sera comme s'il remplaçait l'instruction require par le code du fichier inclus. On voit donc que la fonction maFonction() est définie deux fois, ce qui causera une erreur.

Solution avec require_once

Le problème peut être résolu avec require_once.

Grâce à require_once, PHP effectuera une vérification supplémentaire avant d'inclure la bibliothèque. Ainsi, lors de son « copier-coller virtuel », PHP détectera que la bibliothèque de fonction a déjà été incluse alors il ne l'inclura pas une seconde fois.