Manuel PHP
Précédent | Chapitre 11. 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 11-32. 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-33. 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 J 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-34. 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 été traité 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é
// '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 11-35. 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.

> 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-36. 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()