The require_once() statement replaces
itself with the specified file, much like the C preprocessor's
#include works, and in that respect is
similar to the require() statement. The main
difference is that in an inclusion chain, the use of
require_once() will assure that the code is
added to your script only once, and avoid clashes with variable
values or function names that can happen.
For example, if you create the following 2 include files
utils.inc and foolib.inc
Example 11-2. utils.inc
<?php
define(PHPVERSION, floor(phpversion()));
echo "GLOBALS ARE NICE\n";
function goodTea() {
return "Oolong tea tastes good!";
}
?>
|
|
Example 11-3. foolib.inc
<?php
require ("utils.inc");
function showVar($var) {
if (PHPVERSION == 4) {
print_r($var);
} else {
dump_var($var);
}
}
// bunch of other functions ...
?>
|
|
And then you write a script
cause_error_require.php
Example 11-4. cause_error_require.php
<?php
require("foolib.inc");
/* the following will generate an error */
require("utils.inc");
$foo = array("1",array("complex","quaternion"));
echo "this is requiring utils.inc again which is also\n";
echo "required in foolib.inc\n";
echo "Running goodTea: ".goodTea()."\n";
echo "Printing foo: \n";
showVar($foo);
?>
|
|
When you try running the latter one, the resulting ouptut will be (using
PHP 4.01pl2):
By modifying
foolib.inc and
cause_errror_require.php
to use
require_once()
instead of
require() and renaming the
last one to
avoid_error_require_once.php, we have:
Example 11-5. foolib.inc (fixed)
...
require_once("utils.inc");
function showVar($var) {
...
|
|
Example 11-6. avoid_error_require_once.php
...
require_once("foolib.inc");
require_once("utils.inc");
$foo = array("1",array("complex","quaternion"));
...
|
|
And when running the latter, the output will be (using PHP 4.0.1pl2):
Also note that, analogous to the behavior of the
#include of the C preprocessor, this statement
acts at "compile time", e.g. when the script is parsed and before it
is executed, and should not be used for parts of the script that need
to be inserted dynamically during its execution. You should use
include_once() or include()
for that purpose.
For more examples on using require_once() and
include_once(), look at the PEAR code included in
the latest PHP source code distributions.
See also: require(),
include(), include_once(),
get_required_files(),
get_included_files(), readfile(),
and virtual().