require() 语句包括并运行指定文件,有关包括如何工作的详细信息见 include() 的文档。

require() 和 include() 除了怎样处理失败之外在各方面都完全一样。

include() 产生一个警告而 require() 则导致一个致命错误。换句话说，如果你想在丢失文件时停止处理页面，那就别犹豫了，用 require() 吧。include() 就不是这样，脚本会继续运行。同时也要确认设置了合适的include_path。

例子 16-2. 基本的 require() 例子

1. <?php 
2. require 'prepend.php'; 
3. require $somefile; 
4. require ('somefile.txt'); 
5. ?> 

更多例子参见 include() 文档。

注: 在 php 4.0.2 之前适用以下规则：require() 总是会尝试读取目标文件，即使它所在的行根本就不会执行。条件语句不会影响 require()。不过如果 require() 所在的行没有执行，则目标文件中的代码也不会执行。同样，循环结构也不影响 require() 的行为。尽管目标文件中包含的代码仍然是循环的主体，但 require() 本身只会运行一次。

注: 由于这是一个语言结构而非函数，因此它无法被“变量函数”调用。

include() 语句包括并运行指定文件。

以下文档也适用于 require()。这两种结构除了在如何处理失败之外完全一样。include() 产生一个警告而 require() 则导致一个致命错误。换句话说，如果你想在遇到丢失文件时停止处理页面就用 require()。include() 就不是这样，脚本会继续运行。同时也要确认设置了合适的 include_path。

当一个文件被包括时，其中所包含的代码继承了 include 所在行的变量范围。从该处开始，调用文件在该行处可用的任何变量在被调用的文件中也都可用。

例子 16-3. 基本的 include() 例子 vars.php

1. <?php 
2. $color = 'green'; 
3. $fruit = 'apple'; 
4. ?> 
5. test.php 
6. <?php 
7. echo "a $color $fruit"; // a 
8. include 'vars.php'; 
9. echo "a $color $fruit"; // a green apple 
10. ?> 

如果 include 出现于调用文件中的一个函数里，则被调用的文件中所包含的所有代码将表现得如同它们是在该函数内部定义的一样,所以它将遵循该函数的变量范围。

例子 16-4. 函数中的包括

1. <?php 
2. function foo() 
3. { 
4.    global $color; 
5.    include 'vars.php'; 
6.    echo "a $color $fruit"; 
7. } 
8. /* vars.php is in the scope of foo() so    * 
9.  * $fruit is not available outside of this  * 
10.  * scope.  $color is because we declared it * 
11.  * as global.      */ 
12. foo();    // a green apple 
13. echo "a $color $fruit";  // a green 
14. ?> 

当一个文件被包括时,语法解析器在目标文件的开头脱离 php 模式并进入 html 模式，到文件结尾处恢复。由于此原因，目标文件中应被当作 php 代码执行的任何代码都必须被包括在有效的 php 起始和结束标记之中。

如果“url fopen wrappers”在 php 中被激活（默认配置），可以用 url（通过 http 或者其它支持的封装协议 － 所支持的协议见 附录 l）而不是本地文件来指定要被包括的文件。如果目标服务器将目标文件作为 php 代码解释，则可以用适用于 http get 的 url 请求字符串来向被包括的文件传递变量。严格的说这和包括一个文件并继承父文件的变量空间并不是一回事；该脚本文件实际上已经在远程服务器上运行了，而本地脚本则包括了其结果。

警告:windows 版本的 php 在 4.3.0 版之前不支持本函数的远程文件访问，即使 allow_url_fopen 选项已被激活。

例子 16-5. 通过 http 进行的 include()

1. <?php 
2. include 'file.php?foo=1&bar=2'; 
3. // works. 
4. include 'http://www.example.com/file.php?foo=1&bar=2'; 
5. $foo = 1; 
6. $bar = 2; 
7. include 'file.txt';  // works. 
8. include 'file.php';  // works. 
9. ?> 

相关信息参见使用远程文件，fopen() 和 file(),因为 include() 和 require() 是特殊的语言结构，在条件语句中使用必须将其放在语句组中（花括号中）。

例子 16-6. include() 与条件语句组

1. <?php 
2. // this is wrong and will not work as desired. 
3. if ($condition) 
4.    include $file; 
5. else 
6.    include $other; 
7.  
8. // this is correct. 
9. if ($condition) { 
10.    include $file; 
11. } else { 
12.    include $other; 
13. } 
14. ?> 

处理返回值：可以在被包括的文件中使用 return() 语句来终止该文件中程序的执行并返回调用它的脚本。同样也可以从被包括的文件中返回值。可以像普通函数一样获得 include 呼叫的返回值。

注: 在 php 3 中，除非是在函数中调用否则被包括的文件中不能出现 return。在此情况下 return() 作用于该函数而不是整个文件。

例子 16-7. include()和 return()语句 return.php

1. <?php 
2. $var = 'php'; 
3. return $var; 
4. ?> 

noreturn.php

1. <?php 
2. $var = 'php'; 
3. ?> 

testreturns.php

1. <?php 
2. $foo = include 'return.php'; 
3. echo $foo; // prints 'php' 
4. $bar = include 'noreturn.php'; 
5. echo $bar; // prints 1 
6. ?> 

$bar 的值为 1 是因为 include 成功运行了。注意以上例子中的区别。第一个在被包括的文件中用了 return() 而另一个没有。其它几种把文件“包括”到变量的方法是用 fopen()，file() 或者 include() 连同输出控制函数一起使用。

注: 由于这是一个语言结构而非函数，因此它无法被“变量函数”调用。

require_once() 语句在脚本执行期间包括并运行指定文件。此行为和 require() 语句类似，唯一区别是如果该文件中的代码已经被包括了，则不会再次包括。有关此语句怎样工作参见 require() 的文档。

require_once() 应该用于在脚本执行期间同一个文件有可能被包括超过一次的情况下，你想确保它只被包括一次以避免函数重定义，变量重新赋值等问题。

使用 require_once() 和 include_once() 的例子见最新的 php 源程序发行包中的 pear 代码。

注: require_once() 是 php 4.0.1pl2 中新加入的,要注意 require_once() 和 include_once() 在大小写不敏感的操作系统中（例如 windows）的行为可能不是你所期望的。 例子 16-8. require_once() 在 windows 下不区分大小写

1. <?php 
2. require_once("a.php"); // this will include a.php 
3. require_once("a.php"); // this will include a.php again on windows! 
4. ?> 

警告：windows 版本的 php 在 4.3.0 版之前不支持本函数的远程文件访问，即使 allow_url_fopen 选项已被激活。

include_once() 语句在脚本执行期间包括并运行指定文件。此行为和 include() 语句类似，唯一区别是如果该文件中的代码已经被包括了，则不会再次包括。如同此语句名字暗示的那样，只会包括一次。

include_once() 应该用于在脚本执行期间同一个文件有可能被包括超过一次的情况下，你想确保它只被包括一次以避免函数重定义，变量重新赋值等问题。

使用 require_once() 和 include_once() 的更多例子见最新的 php 源程序发行包中的 pear 代码。

注: include_once() 是 php 4.0.1pl2 中新加入的, 要注意 include_once() 和 require_once() 在大小写不敏感的操作系统中（例如 windows）的行为可能不是你所期望的。 

例子16-9:include_once()在windows下不区分大小写:

1. <?php 
2. include_once("a.php"); // this will include a.php 
3. include_once("a.php"); // this will include a.php again on windows! 
4. ?> 

警告:windows 版本的 php 在 4.3.0 版之前不支持本函数的远程文件访问，即使 allow_url_fopen 选项已被激活。