The require() statement replaces itself with the specified file, much like the C preprocessor’s#includeworks.
If "URL fopen wrappers" are enabled in PHP (which they are in the default configuration), you can specify the file to be require()ed using an URL instead of a local pathname. SeeRemote filesand fopen() for more information.
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 PHP mode again at the end. For this reason, any code inside the target file which should be executed as PHP code must be enclosed withinvalid PHP start and end tags.
require() is not actually a function in PHP; rather, it is a language construct. It is subject to some different rules than functions are. For instance, require() is not subject to any containing control structures. For another, it does not return any value; attempting to read a return value from a require() call results in a parse error.
Unlike include(), require() will always read in the target file, even if the line it’s on never executes. If you want to conditionally include a file, use include(). The conditional statement won’t affect the require(). However, if the line on which the require() occurs is not executed, neither will any of the code in the target file be executed.
Similarly, looping structures do not affect the behaviour of require(). Although the code contained in the target file is still subject to the loop, the require() itself happens only once.
This means that you can’t put a require() statement inside of a loop structure and expect it to include the contents of a different file on each iteration. To do that, use an include() statement.
require (’header.inc’);
When a file is require()ed, the code it contains inherits the variable scope of the line on which the require() occurs. Any variables available at that line in the calling file will be available within the called file. If the require() 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 require()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 require()ed file using an URL request string as used with HTTP GET. This is not strictly speaking the same thing as require()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 require()ed file. */
/* Won’t work; file.txt wasn’t handled by someserver. */
require ("http://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. */
require ("file.php?varone=1&vartwo=2");
/* Works. */
require ("http://someserver/file.php?varone=1&vartwo=2");
$varone = 1;
$vartwo = 2;
require ("file.txt"); /* Works. */
require ("file.php"); /* Works. */
In PHP 3, it is possible to execute areturnstatement inside a require()ed file, as long as that statement occurs in the global scope of the require()ed file. It may not occur within any block (meaning inside braces ({}). In PHP 4, however, this ability has been discontinued. If you need this functionality, see include().
See also include(), require_once(), include_once(), readfile(), and virtual().
include()
The include() statement includes and evaluates the specified file.
If "URL fopen wrappers" are enabled in PHP (which they are in the default configuration), you can specify the file to be include()ed using an URL instead of a local pathname. SeeRemote filesand fopen() for more information.
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 withinvalid 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 anifstatement 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 PHP 3 and PHP 4, it is possible to execute areturnstatement 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 PHP 3, thereturnmay not appear inside a block unless it’s a function block, in which case thereturn applies to that function and not the whole file. In PHP 4, however, this restriction does not exist. Also, PHP 4 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 PHP 3.
Example 11-1. include() in PHP 3 and PHP 4
Assume the existence of the following file (namedtest.inc) in the same directory as the main file:
<?php
echo "Before the return <br>\n";
if (1) {
Chapter 11. Control Structures
return 27;
}
echo "After the return <br>\n";
?>
Assume that the main file (main.html) contains the following:
<?php
$retval = include (’test.inc’);
echo "File returned: ’$retval’<br>\n";
?>
Whenmain.htmlis 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 thatmain.htmlhas 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
However, PHP 3 will give the following output:
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 thereturnstatement 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 supportreturning 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 ("http://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 ("http://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().