diff --git a/language/control-structures.xml b/language/control-structures.xml
index 6383f829c6..4dfafe83de 100644
--- a/language/control-structures.xml
+++ b/language/control-structures.xml
@@ -867,6 +867,11 @@ require ("file.inc"); /* $varone and $vartwo will be available in file.inc */
has been discontinued. If you need this functionality, see
include.
+
+ See also include, require_once,
+ include_once, readfile,
+ and virtual.
+
@@ -1047,38 +1052,177 @@ include ("file.inc"); /* $varone and $vartwo will be available in file.inc */
files feature; the above holds true regardless.
- See also readfile,
- require, and virtual.
+ See also require, require_once,
+ include_once, readfile,
+ and virtual.
<function>require_once</function>
-
- TODO: The require_once statement replaces
- itself with the specified file, much like the C preprocessor's
- #include works.
-
- Seel also: require,
+ 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
+
+ utils.inc
+
+<?php
+define(PHPVERSION, floor(phpversion()));
+echo "GLOBALS ARE NICE\n";
+function goodTea() {
+ return "Oolong tea tastes good!";
+}
+?>
+
+
+
+ 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
+
+ cause_error_require.php
+
+<?php
+require("foolib.inc");
+/* the following will generate and 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: ".showVar($foo);
+?>
+
+
+ When you try running the latter one, the resulting ouptut will be (using
+ PHP 4.01pl2):
+
+
+GLOBALS ARE NICE
+GLOBALS ARE NICE
+
+Fatal error: Cannot redeclare causeerror() in utils.inc on line 5
+
+
+ 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:
+
+ foolib.inc (fixed)
+
+...
+require_once("utils.inc");
+function showVar($var) {
+...
+
+
+
+ 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):
+
+
+GLOBALS ARE NICE
+this is requiring globals.inc again which is also
+required in foolib.inc
+Running showIt: Oolong tea tastes good!
+Array
+(
+ [0] => 1
+ [1] => Array
+ (
+ [0] => complex
+ [1] => quaternion
+ )
+
+)
+
+
+
+
+ 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
+ get_included_files, readfile,
+ and virtual.
<function>include_once</function>
-
- TODO: The include_once statement replaces
- itself with the specified file, much like the C preprocessor's
- #include works.
-
- Seel also: require,
+ The include_once statement includes and evaluates
+ the specified file during the execution of the script.
+ This is a behavior similar to the include statement,
+ with the important difference that if the code from a file has already
+ been included, it will not be included again.
+
+
+ As mentioned in the require_once description, the
+ include_once should be used in the cases in which
+ the same file might be included and evaluated more than once during a
+ particular execution of a script, and you want to be sure that it is
+ included exactly once to avoid problems with function redefinitions,
+ variable value reassignments, etc.
+
+
+ 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, require_once,
get_required_files,
- get_included_files
+ get_included_files, readfile,
+ and virtual.