include()
Het include() statement voegt het aangegeven bestand in en evalueert deze.
Als de "URL fopen wrappers" zijn ingeschakeld (in de default configuratie is dit het geval), dan kun je een file ook include()n met een URL, in plaats van een lokale path naam. Zie Remote files en fopen() voor meer informatie hierover.
Een belangrijke opmerking plaatsen we hier over bestanden die worden ge-include()ed of ge-require()ed. Deze functies zorgen er beide voor dat de parser PHP mode verlaat en overgaat in HTML mode voor de opgegeven files aan het begin van het bestand, en aan het einde van dit bestand weer in PHP mode overgaat. Daarom moet de inhoud van deze bestanden worden omgeven met geldige PHP begin en einde tags.
Dit gebeurt iedere keer als include() statement wordt tegengekomen, daarom kun je met een include() in een loop structuur een aantal verschillende files invoegen.
$files = array ('first.inc', 'second.inc', 'third.inc');
for ($i = 0; $i < count($files); $i++) {
include $files[$i];
}
include() verschilt van het require() statement op éé punt. Een include() statement wordt elke keer ge-evalueerd als deze wordt tegengekomen (en ook alleen maar tijdens de uitvoering van een script). Dit in tegenstelling tot het require() statement, welke wordt vervangen door de opgegeven file als deze voor de eerste keer wordt tegenkomen.
Omdat include() een speciale taal constructie is, ben je verplicht deze te omgeven met een statement blok als het include() statement zich in een conditionele constructie bevind.
/* Dit is FOUT en zal niet werken zoals het bedoeld is */
if ($condition)
include($file);
else
include($other);
/* Dit is GOED. */
if ($condition) {
include($file);
} else {
include($other);
}
In zowel PHP 3 als PHP 4, is het mogelijk om een return statement uit te voeren in een ge-include() file, om bijvoorbeeld een fout conditie terug te geven aan het script wat het bestand uitvoerde. Er zijn wel verschillen in de manier waarop dit werkt. Het eerste verschil is dat in PHP 3 het return statement zich niet binnen een blok mag bevinden, tenzij het een functie blok betreft. In dit laatste geval heeft het return statement natuurlijk betrekking op de functie, en niet op de gehele file. In PHP 4 bestaat deze restrictie echter niet. Het is in PHP 4 ook mogelijk om waardes terug te geven vanuit include()d files. Je kunt dan de return waarde van het include() statement gebruiken net zoals een gewone functie. In PHP 3 zal dit een parse error genereren.
Example#1 include() in PHP 3 en PHP 4
Naam aan dat het volgende bestand bestaat (genoemd test.inc) en dat deze zich in dezelfde directory bevindt als het hoofdscript:
<?php
echo "Voor de return <br>\n";
if (1) {
return 27;
}
echo "Na de return <br>\n";
?>
Naam aan dat het hoofdscript, (main.html) het volgende bevat:
<?php
$retval = include ('test.inc');
echo "File returned: '$retval'<br>\n";
?>
When main.html is called in PHP 3, it will generate a parse error on line 2; you can't take the value of an include() in PHP 3. In PHP 4, however, the result will be:
Before the return
File returned: '27'
Now, assume that main.html has been altered to contain the following:
<?php
include ('test.inc');
echo "Back in main.html<br>\n";
?>
In PHP 4, the output will be:
Before the return
Back in main.html
Before the return
27Back in main.html
Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5
The above parse error is a result of the fact that the return statement is enclosed in a non-function block within test.inc. When the return is moved outside of the block, the output is:
Before the return
27Back in main.html
The spurious '27' is due to the fact that PHP 3 does not support returning values from files like that.
When a file is include()ed, the code it contains inherits the variable scope of the line on which the include() occurs. Any variables available at that line in the calling file will be available within the called file. If the include() occurs inside a function within the calling file, then all of the code contained in the called file will behave as though it had been defined inside that function.
If the include()ed file is called via HTTP using the fopen wrappers, and if the target server interprets the target file as PHP code, variables may be passed to the include()ed file using an URL request string as used with HTTP GET. This is not strictly speaking the same thing as include()ing the file and having it inherit the parent file's variable scope; the script is actually being run on the remote server and the result is then being included into the local script.
/* This example assumes that someserver is configured to parse .php
* files and not .txt files. Also, 'works' here means that the variables
* $varone and $vartwo are available within the include()ed file. */
/* Won't work; file.txt wasn't handled by someserver. */
include ("https://someserver/file.txt?varone=1&vartwo=2");
/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
* on the local filesystem. */
include ("file.php?varone=1&vartwo=2");
/* Works. */
include ("https://someserver/file.php?varone=1&vartwo=2");
$varone = 1;
$vartwo = 2;
include ("file.txt"); /* Works. */
include ("file.php"); /* Works. */
See also require(), require_once(), include_once(), readfile(), and virtual().