La fonction include() inclut et exécute le fichier spécifié en argument.

Les fichiers à inclure sont d’abord recherchés dans le dossier désigné par “include_path”, relativement au dossier courant, puis dans “include_path”, relativement au dossier de travail du script. Par exemple, si “include_path” est “.”, que le dossier de travail est “/www/”, et que vous incluez le fichier “include/a.php” et qu’il y a une instruction “include “b.php”” dans ce fichier, alors “b.php” est d’abord recherché dans “/www/”, puis dans “/www/include/”. Si le nom du fichier commence par “./” ou “../”, il est cherché uniquement dans l’“include_path” relatif au dossier courant d’exécution.

Lorsqu’un fichier est inclus, le code le composant hérite de la portée des variables de la ligne où l’inclusion apparaît. Toutes les variables disponibles à cette ligne dans le fichier appelant seront disponibles dans le fichier appelé, à partir de ce point. Cependant, toutes les fonctions et classes définies dans le fichier inclu ont une portée globale.

vars.php
<?php
 
$couleur = 'verte';
$fruit = 'pomme';
 
?>
 
test.php
<?php
 
echo "Une $couleur $fruit"; // Une
 
include 'vars.php';
 
echo "Une $couleur $fruit"; // Une verte pomme
 
?>

Si l’inclusion intervient à l’intérieure d’une fonction, le code inclus sera alors considéré comme faisant partie de la fonction. Cela modifie donc le contexte de variables accessibles.

<?php
 
function foo() {
    global $couleur;
 
    include 'vars.php';
 
    echo "Une $couleur $fruit";
}
 
/* vars.php est dans le contexte de foo()    *
 * donc $fruit n'est pas disponibles hors de  *
 * cette fonction. $couleur l'est, car c'est *
 * une variable globale                      */
 
foo();                      // Une verte pomme
echo "Une $couleur $fruit"; // Une verte
 
?>

<?php
 
/* Cet exemple suppose que www.example.com est configuré pour traiter
 * les fichiers .php et non pas les fichiers .txt. De plus,
 * 'Work' signifie ici que les variables
 * $foo et $bar sont disponibles dans le fichier inclus
 */
 
// Ne fonctionne pas : file.txt n'a pas été traité par www.example.com comme du PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';
 
// Ne fonctionne pas : le script cherche un fichier nommé
// 'file.php?foo=1&bar=2' sur le système local
include 'file.php?foo=1&bar=2';
 
// Réussi
include 'http://www.example.com/file.php?foo=1&bar=2';
 
$foo = 1;
$bar = 2;
include 'file.txt';  // OK.
include 'file.php';  // OK.
?>

Voir aussi travailler avec les fichiers distants, fopen() et file() pour des informations reliées.

Comme include() est une structure de langage particulière, les parenthèses ne sont pas nécessaires autour de l’argument. Faites attention lorsque vous comparez la valeur retournée.

<?php
// ne fonctionne pas, évaluer comme include(('vars.php') == 'OK'), i.e. include('')
if (include('vars.php') == 'OK') {
    echo 'OK';
}
 
// fonctionne
if ((include 'vars.php') == 'OK') {
    echo 'OK';
}
?>

Note : En PHP 3, le return() n’est pas utilisable à moins que ce ne soit dans un bloc de fonction, auquel cas le return() s’applique à une fonction et non pas au fichier.

return.php
<?php
 
$var = 'PHP';
 
return $var;
 
?>
 
noreturn.php
<?php
 
$var = 'PHP';
 
?>
 
testreturns.php
<?php
 
$foo = include 'return.php';
 
echo $foo; // affiche 'PHP'
 
$bar = include 'noreturn.php';
 
echo $bar; // affiche 1
 
?>

“$bar” a la valeur de “1” car l’inclusion était réussie. Notez la différence entre les deux exemples ci-dessus. Le premier utilise la commande return() dans le fichier inclus, alors que le second ne le fait pas. Si le fichier ne peut être inclus, “FALSE” est retourné et une erreur de niveau “E_WARNING” est envoyée.

S’il y a des fonctions de définies dans le fichier inclus, elles peuvent être utilisées dans le fichier principal si elles sont avant le return() ou après. Si le fichier est inclus deux fois, PHP 5 enverra une erreur fatale car les fonctions seront déjà déclarées, tandis que PHP 4 ne se plaindra pas des fonctions définies après return(). Il est recommandé d’utiliser include_once() au lieu de vérifier si le fichier a déjà été inclus et donc de retourner conditonnellement l’inclusion du fichier.

Une autre façon d’inclure un fichier PHP dans une variable est de capturer la sortie en utilisant les fonctions de contrôle de sortie avec include(). Par exemple :

<?php
$string = get_include_contents('somefile.php');
 
function get_include_contents($filename) {
  if (is_file($filename)) {
    ob_start();
    include $filename;
    $contents = ob_get_contents();
    ob_end_clean();
    return $contents;
  }
  return false;
}
 
?>

Note : Comme ceci est une structure du langage, et non pas une fonction, il n’est pas possible de l’appeler avec les variables fonctions.