PHP学习之十一：关于include指令

include()

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

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

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

例子 11-3. 基本的 include() 例子

vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

?>

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

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

<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
* $fruit is NOT available outside of this  *
* scope.  $color is because we declared it *
* as global.                               */

foo();                    // A green apple
echo "A $color $fruit";   // A green

?>

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

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

警告

Windows 版本的 PHP 在 4.3.0 版之前不支持该函数的远程文件访问，即使 allow_url_fopen 选项已被激活。

例子 11-5. 通过 HTTP 进行的 include()

<?php

/* This example assumes that www.example.com is configured to parse .php *
* files and not .txt files. Also, 'Works' here means that the variables *
* $foo and $bar are available within the included file.                 */

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>

相关信息参见使用远程文件，fopen() 和 file()。

因为 include() 和 require() 是特殊的语言结构，在条件语句中使用必须将其放在语句组中（花括号中）。

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

<?php

// This is WRONG and will not work as desired.
if ($condition)
    include $file;
else
    include $other;


// This is CORRECT.
if ($condition) {
    include $file;
} else {
    include $other;
}

?>

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

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

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

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>

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

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

 

include_once()

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

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

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

注: include_once() 是 PHP 4.0.1pl2 中新加入的。

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

例子 11-9. include_once() 在 Windows 下不区分大小写

<?php
include_once("a.php"); // this will include a.php
include_once("A.php"); // this will include a.php again on Windows!
?>

警告

Windows 版本的 PHP 在 4.3.0 版之前不支持该函数的远程文件访问，即使 allow_url_fopen 选项已被激活。

参见 include()，require()，require_once()，get_required_files()，get_included_files()，readfile() 和 virtual()。