Manuel PHP
PrécédentChapitre 11. Les structures de contrôleSuivant

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. include() produit une Alerte (warning) tandis que 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.

Lorsqu'un fichier est inclus, le code qu'il contient hérite des variables qui existent dans ce contexte. Toute variable accessible à la ligne qui réalise l'exécution est aussi accessible dans le fichier inclus.

Exemple 11-30. Exemple avec include()

vars.php
<?php

$couleur = 'verte';
$fruit = 'pomme';

?>

test.php
<?php

echo "Une $couleur $fruit"; // Une

include 'vars.php';

echo "Une $coleur $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.

Exemple 11-31. 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 dispnibles 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 Annexe I 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

La version Windows de PHP ne supporte pas l'accès aux fichiers distants avec cette fonction, même si allow_url_fopen est activé.

Exemple 11-32. Utiliser include() via HTTP

<?php

/* Cet exemple suppose que www.exemple.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 &eacute;t&eacute; trait&eacute; par www.exemple.com comme du PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Ne fonctionne pas : le script cherche un fichier nomm&eacute;
// 'file.php?foo=1&bar=2' sur le syst&egrave;me local
include 'file.php?foo=1&bar=2';

// R&eacute;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() et require() sont des structures du langage particulières, vous devez les placer dans un bloc s'ils sont placés dans un bloc conditionnel.

Exemple 11-33. include() et les conditions

<?php

// Ceci est FAUX et &eacute;chouera
if ($condition)
    include $file;
else
    include $other;


// Ceci est CORRECT.
if ($condition) {
    include $file;
} else {
    include $other;
}

?>

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.

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.

Exemple 11-34. include() et return()

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 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. Un autre moyen d'inclure des fichiers dans des variables est d'utiliser la fonction fopen() ou file() ou d'utiliser include() avec les fonctions de contrôle de sortie.

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.

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

PrécédentSommaireSuivant
require()Niveau supérieurrequire_once()