Manuel PHP
Précédent | Chapitre 15. Les structures de contrôle | Suivant

# 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. Soyez prévenus qu'une erreur d'analyse dans un fichier inclut ne cause pas l'arrêt du script.

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/`.

Exemple 15-33. Exemple avec include()

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

Exemple 15-34. 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 L 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 15-35. 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.
?>`

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 15-36. include() et les conditions

`<?php // Ceci est FAUX et é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.

Parceque include() est un constructeur de langage spécial, les parenthèses ne sont pas nécessaires autour de l'argument. Faîte attention lorsque vous comparez la valeur retournée.

Exemple 15-37. Comparaison de la valeur de retour d'un include

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

Exemple 15-38. 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. 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édent | Sommaire | Suivant
require() | Niveau supérieur | require_once()