From 1debec1be1da2e448a22941b3bc0ff759390f460 Mon Sep 17 00:00:00 2001 From: cslawi Date: Tue, 7 Dec 1999 00:02:38 +0000 Subject: [PATCH] Further explanations on the behaviour of include() and require(). Also gives differences between PHP3 and PHP4 when using these statements. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@16743 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/control-structures.sgml | 290 ++++++++++++++++++++++++------- 1 file changed, 231 insertions(+), 59 deletions(-) diff --git a/language/control-structures.sgml b/language/control-structures.sgml index 234c40cf8e..1df018cf8c 100644 --- a/language/control-structures.sgml +++ b/language/control-structures.sgml @@ -617,22 +617,63 @@ switch ($i): - - <literal>require</literal> - - - The require statement replaces itself with the - specified file, much like the C preprocessor's #include works. + + <function>require</function> + + + The require statement replaces itself with + the specified file, much like the C preprocessor's + #include works. + - - 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. + + 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. + + + + 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'; +require( 'header.inc' ); @@ -648,58 +689,86 @@ switch ($i): part of the calling file. -include( "file.inc?varone=1&vartwo=2" ); /* Won't work. */ +require( "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 */ - +require( "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. + + + + In PHP3, 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 PHP4, however, this ability + has been discontinued. If you need this functionality, see + include. + + - - <literal>include</literal> + + <function>include</function> + + + The include statement includes and evaluates + the specified file. + - - The include statement includes and evaluates - the specified file. - - - 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 file. - - - - $files = array ('first.inc', 'second.inc', 'third.inc'); - for ($i = 0; $i < count($files); $i++) { - include $files[$i]; - } - - + + 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. + - 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). + 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. - - Because include is a - special language construct, you must enclose it within a statement - block if it is inside a conditional block. + + +$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) @@ -714,13 +783,108 @@ include( "file.inc" ); /* $varone and $vartwo will be available in file.inc */ } else { include($other); } - - + + + - - When the file is evaluated, the parser begins in "HTML-mode" which - will output the contents of the file until the first PHP start tag - (<?) is encountered. + + In both PHP3 and PHP4, 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 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 + includeed files. You can take the value of the + include call as you would a normal + function. This generates a parse error in PHP3. + + + + <function>include</function> in PHP3 and PHP4 + + Assume the existence of the following file (named + test.inc) in the same directory as the main + file: + +<?php +echo "Before the return <br>\n"; +if ( 1 ) { + 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"; +?> + + + + + When main.html is called in PHP3, it will + generate a parse error on line 2; you can't take the value of an + include in PHP3. In PHP4, however, the + result will be: + +Before the return +File returned: '27' + + + + + Now, assume that main.html has been altered + to contain the following: + +<?php +include( 'test.inc' ); +echo "Back in main.html<br>\n"; +?> + + + + + In PHP4, the output will be: + +Before the return +Back in main.html + + However, PHP3 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.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 PHP3 does not support + returning values from files like that. + + + Please note that both include and @@ -743,9 +907,17 @@ include( "file.inc" ); /* $varone and $vartwo will be available in file.inc */ - - See also readfile, require, - virtual. + + 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. + +