include()

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

Cette documentation s'applique aussi � la fonction require(). Les deux structures de langage sont identiques, hormis dans leur gestion des erreurs. Ils produisent tous les deux une Alerte mais require() g�n�re une erreur fatale. En d'autres termes, n'h�sitez pas � utiliser require() si vous voulez qu'un fichier d'inclusion manquant interrompe votre script. include() ne se comporte pas de cette fa�on, et le script continuera son ex�cution. Assurez-vous d'avoir bien configur� le include_path aussi. Soyez pr�venus qu'une erreur d'analyse dans un fichier inclut ne cause pas l'arr�t du script en PHP dans les versions ant�rieures � 4.3.5. Depuis ces versions, il le peut.

Les fichiers � inclure sont d'abord recherch�s dans chaque dossier de include_path, relativement au dossier courant, puis dans le 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/libraries/, puis dans /www/include/. Si le nom du fichier commence par ./ ou ../, il est cherch� uniquement dans le dossier courant d'ex�cution ou dans le dossier parent, respectivement.

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 inclus ont une port�e globale.

Exemple #1 Exemple avec include()

vars.php
<?php

$color 
'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�rieur d'une fonction, le code inclus sera alors consid�r� comme faisant partie de la fonction. Cela modifie donc le contexte de variables accessibles. Une exception � cette r�gle : les constantes magiques sont analys�es par l'analyseur avant que l'inclusion n'intervienne.

Exemple #2 Inclusion de fichiers dans une fonction

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

?>

Il est important de noter que lorsqu'un fichier est include() ou require(), les erreurs d'analyse appara�tront en HTML tout au d�but du fichier, et l'analyse du fichier parent ne sera pas interrompue. Pour cette raison, le code qui est dans le fichier doit �tre plac� entre les balises habituelles de PHP.

Si les Gestionnaires d'URL sont activ�s dans PHP (ce qui est le cas par d�faut), vous pouvez localiser le fichier avec une URL (via HTTP ou bien avec un gestionnaire adapt� : voir Liste des protocoles support�s pour une liste des protocoles), au lieu d'un simple chemin local. Si le serveur distant interpr�te le fichier comme du code PHP, des variables peuvent �tre transmises au serveur distant via l'URL et la m�thode GET. Ce n'est pas, � strictement parler, la m�me chose que d'h�riter du contexte de variable. Le fichier inclus est en fait un script ex�cut� � distance, et son r�sultat est inclus dans le code courant.

Avertissement

Les versions Windows de PHP ant�rieures � la version 4.3.0 ne supportent pas l'acc�s aux fichiers distants avec cette fonction, m�me si allow_url_fopen est activ�.

Exemple #3 Utiliser include() via HTTP

<?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.

?>

Avertissement

Alerte de s�curit�

Un fichier distant peut �tre trait� sur le serveur distant (d�pendamment de l'extension du fichier et si le serveur distant ex�cute PHP ou non) mais il doit toujours produire un script PHP valide parce qu'il sera trait� sur le serveur local. Si le fichier du serveur distant doit �tre trait� sur place et affich� seulement, readfile() est une fonction beaucoup plus appropri�e. Autrement, vous devriez bien faire attention � s�curiser le script distant afin qu'il produise un code valide et d�sir�.

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

Gestion du retour : il est possible d'ex�cuter une commande return() dans un fichier inclus pour en terminer le traitement et retourner au fichier appelant. De plus, il est possible de retourner des valeurs des fichiers inclus. Vous pouvez prendre et traiter la valeur retourn�e par la fonction, comme toute autre fonction. Ce n'est cependant pas possible lors de l'inclusion de fichier distant � moins que le fichier distant a des balises valides de d�but et de fin de script PHP (comme avec les fichiers locaux). Vous pouvez d�clarer les variables n�cessaire dans ces tags et elles seront introduites � l'endroit o� le fichier a �t� inclus.

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.

Exemple #4 Comparaison de la valeur de retour d'une inclusion

<?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';
}
?>

Exemple #5 include() et return()

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 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 conditionnellement 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 :

Exemple #6 Utilisation de la sortie du buffer pour inclure un fichier PHP dans une cha�ne

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

?>

Pour automatiquement inclure des fichiers dans vos scripts, voyez �galement les options de configuration auto_prepend_file et auto_append_file du php.ini.

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

Voir aussi require(), require_once(), include_once(), get_included_files(), readfile(), virtual(), et include_path.