include()

The include() statement includes and evaluates the specified file.

An important note about how this works is that when a file is include()ed or require()ed, parsing drops out of PHP mode and into HTML mode at the beginning of the target file, and resumes again at the end. For this reason, any code inside the target file which should be executed as PHP code must be enclosed within valid PHP start and end tags.

This happens each time the include() statement is encountered, so you can use an include() statement within a looping structure to include a number of different files.

$files = array ('first.inc', 'second.inc', 'third.inc');
for ($i = 0; $i < count($files); $i++) {
    include $files[$i];
}
	 

include() differs from require() in that the include statement is re-evaluated each time it is encountered (and only when it is being executed), whereas the require() statement is replaced by the required file when it is first encountered, whether the contents of the file will be evaluated or not (for example, if it is inside an if statement whose condition evaluated to false).

Because include() is a special language construct, you must enclose it within a statement block if it is inside a conditional block.

 /* This is WRONG and will not work as desired. */
 
 if ($condition)
     include($file);
 else
     include($other);
 
 /* This is CORRECT. */
 
 if ($condition) {
     include($file);
 } else {
     include($other);
 }
	 

In both PHP3 and PHP4, it is possible to execute a return statement inside an include()ed file, in order to terminate processing in that file and return to the script which called it. Some differences in the way this works exist, however. The first is that in PHP3, the return may not appear inside a block unless it's a function block, in which case the return applies to that function and not the whole file. In PHP4, however, this restriction does not exist. Also, PHP4 allows you to return values from include()ed files. You can take the value of the include() call as you would a normal function. This generates a parse error in PHP3.

<?php
echo "Before the return <br>\n";
if ( 1 ) {
   return 27;
}
echo "After the return <br>\n";
?>
	 

<?php
$retval = include( 'test.inc' );
echo "File returned: '$retval'<br>\n";
?>
	 

Before the return
File returned: '27'
	 

<?php
include( 'test.inc' );
echo "Back in main.html<br>\n";
?>
	 

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
	 

Before the return
27Back in main.html
	 

Please note that both include() and require() actually pull the contents of the target file into the calling script file itself; they do not call the target via HTTP or anything like that. So any variable set in the scope in which the inclusion happens will be available within the included file automatically, since it has effectively become a part of the calling file.

include( "file.inc?varone=1&vartwo=2" ); /* Won't work. */

$varone = 1;
$vartwo = 2;
include( "file.inc" );  /* $varone and $vartwo will be available in file.inc */

	 

Don't be misled by the fact that you can require or include files via HTTP using the Remote files feature; the above holds true regardless.

See also readfile(), require(), and virtual().