require
<<<		 include require_once
>>>
4.7 Les structures de contrôle
4 Référence
 Manuel PHP
. if
. else
. elseif
. Syntaxe alternative
. while
. do..while
. for
. foreach
. break
. continue
. switch
. declare
. return
. require
->include
. require_once
. include_once

4.7.15 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 avec include

vars.php
<?php

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

?>

test.php
<?php

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

include 'vars.php';

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

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

Attention

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

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.

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.

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 .

<< include >>
require Les structures de contrôle require_once