From 43bae8ab7ac70e699f9d4ff8e0787b7889e1a55e Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Sat, 19 Jan 2002 10:37:31 +0000 Subject: [PATCH] include/require: Update reflects change in behavoir as of 4.0.2. PHP3 info condensed into a Duplicate info removed, most docs are within include() *_once : Updated. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@68101 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/control-structures.xml | 718 +++++++++++++------------------- 1 file changed, 281 insertions(+), 437 deletions(-) diff --git a/language/control-structures.xml b/language/control-structures.xml index aa3d5220ae..e104c7c870 100644 --- a/language/control-structures.xml +++ b/language/control-structures.xml @@ -1,5 +1,5 @@ - + Control Structures @@ -34,7 +34,7 @@ if (expr) As described in the section about expressions, expr is evaluated to its Boolean value. If expr evaluates to &true;, - PHP will execute statement, and if it evaluates + PHP will execute statement, and if it evaluates to &false; - it'll ignore it. More information about what values evaluate to &false; can be found in the 'Converting to boolean' @@ -1020,499 +1020,340 @@ print_r (profile (TRUE)); - + + <function>require</function> + - The require statement replaces itself with - the specified file, much like the C preprocessor's - #include works. + The require statement includes and evaluates + the specific file. - If "URL fopen wrappers" are enabled in PHP (which they are in the - default configuration), you can specify the file to be - requireed using an URL instead of a local - pathname. See Remote - files and fopen for more information. + require includes and evaluates a specific file. + Detailed information on how this inclusion works is described in the + documentation for include. - An important note about how this works is that when a file is - includeed or requireed, - 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 within valid 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. + require and include + are identical in every way except how they handle failure. + include produces a + Warning while + require results in a + Fatal Error. In other words, don't hesitate to use + require if you want a missing file to halt processing + of the page. include does not behave this way, the + script will continue regardless. Be sure to have an appropriate + include_path setting as well. - 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. - + + Basic <function>require</function> examples - + - + - When a file is requireed, 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 requireed 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 - requireed file using an URL request string as - used with HTTP GET. This is not strictly speaking the same thing - as requireing 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. - - - - - - - - In PHP 3, it is possible to execute a return - statement inside a requireed file, as long as - that statement occurs in the global scope of the - requireed 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 the include documentation for more examples. + + + Prior to PHP 4.0.2, the following applies: require will + always attempt to read the target file, even if the line it's on never executes. + The conditional statement won't affect 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. + + See also include, require_once, - include_once, readfile, - and virtual. + include_once, eval, + file, readfile, + virtual and include_path. - + <function>include</function> 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 - includeed using an URL instead of a local - pathname. See Remote - files and fopen for more information. + The documentation below also applies to require. + The two constructs are identical in every way except how they handle + failure. include produces a + Warning while require + results in a Fatal Error. + In other words, don't hesitate to use require if you want + a missing file to halt processing of the page. include does + not behave this way, the script will continue regardless. Be sure to have an + appropriate include_path setting as well. - An important note about how this works is that when a file is - includeed or requireed, - 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. + When a file is included, 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, from that + point forward. - 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. - - + + Basic <function>include</function> example + + +test.php + +]]> + + + + + 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. So, it will follow + the variable scope of that function. + + + + Including within functions + + ]]> - + + + When a file is included, 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. + + + If "URL fopen wrappers" + are enabled in PHP (which they are in the default configuration), + you can specify the file to be included using an URL (via HTTP) + instead of a local pathname. If the target server interprets + the target file as PHP code, variables may be passed to the included + file using an URL request string as used with HTTP GET. This is + not strictly speaking the same thing as including 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. + - 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. - + + <function>include</function> through HTTP +]]> + + + See also Remote files, + fopen and file for related + information. + + + Because include and require + are special language constructs, you must enclose them within a statement + block if it's inside a conditional block. + + + + include() and conditional blocks + + ]]> - + - In both PHP 3 and PHP 4, it is possible to execute a - return statement inside an - includeed 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, 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 PHP 4, however, this restriction does not - exist. Also, PHP 4 allows you to return values from - includeed files. You can take the value of - the include call as you would a normal - function. This generates a parse error in PHP 3. - - - <function>include</function> in PHP 3 and PHP 4 - - Assume the existence of the following file (named - test.php) in the same directory as the main - file: - -\n"; -if (1) { - return 27; -} -echo "After the return
\n"; -?> -]]> - - - - Assume that the main file (main.html) - contains the following: - -\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: - -\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 the - return statement is enclosed in a non-function - block within test.php. 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 includeed, 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. + Handling Returns: It is possible to execute a return + statement inside an included file in order to terminate processing in that + file and return to the script which called it. Also, it's possible to return + values from included files. You can take the value of the include call as + you would a normal function. + + + In PHP 3, 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. + + - If the includeed 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 - includeed file using an URL request string as - used with HTTP GET. This is not strictly speaking the same thing - as includeing 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. - - + + <function>include</function> and the <function>return</function> statement + -$varone = 1; -$vartwo = 2; -include ("file.txt"); /* Works. */ -include ("file.php"); /* Works. */ +noreturn.php + + +getfoo.php + ]]> - - + + + + $bar is the value (1) because the include was successful. + Notice the difference between the above examples. The first uses + return within the included file while the other does not. + A few other ways to "include" files into variables are with + fopen, file or by using + include along with + Output Control Functions. + + See also require, require_once, include_once, readfile, - and virtual. + virtual, and + include_path. - - + + + <function>require_once</function> - 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. + The require_once statement includes and evaluates + the specified file during the execution of the script. + This is a behavior similar to the require statement, + with the only difference being that if the code from a file has already + been included, it will not be included again. See the documentation for + require for more information on how this statement + works. - For example, if you create the following 2 include files - utils.php and foolib.php - - utils.php - - -]]> - - - - foolib.php - - -]]> - - - And then you write a script cause_error_require.php - - cause_error_require.php - - -]]> - - - When you try running the latter one, the resulting ouptut will be (using - PHP 4.01pl2): - - - - - - By modifying foolib.php 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.php (fixed) - - - - - - avoid_error_require_once.php - - - - - And when running the latter, the output will be (using PHP 4.0.1pl2): - - - 1 - [1] => Array - ( - [0] => complex - [1] => quaternion - ) - -) -]]> - - + require_once should be used in cases where + 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. - 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. + For examples on using require_once and + include_once, look at the + PEAR code included in the + latest PHP source code distributions. + + + require_once was added in PHP 4.0.1pl2 + + See also: require, include, include_once, @@ -1522,18 +1363,18 @@ Array - + <function>include_once</function> 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. + with the only difference being that if the code from a file has already + been included, it will not be included again. As the name suggests, + it will be included just once. - As mentioned in the require_once description, the - include_once should be used in the cases in which + include_once should be used in cases where 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, @@ -1541,15 +1382,18 @@ Array For more examples on using require_once and - include_once, look at the PEAR code included in - the latest PHP source code distributions. + include_once, look at the + PEAR code included in the latest + PHP source code distributions. - + + include_once was added in PHP 4.0.1pl2 - + + - See also: require, - include, require_once, + See also include, + require, require_once, get_required_files, get_included_files, readfile, and virtual.