<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>include</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="PHP 手册"
HREF="index.html"><LINK
REL="UP"
TITLE="控制结构"
HREF="language.control-structures.html"><LINK
REL="PREVIOUS"
TITLE="require"
HREF="function.require.html"><LINK
REL="NEXT"
TITLE="require_once"
HREF="function.require-once.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=UTF-8"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP 手册</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.require.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>章 16. 控制结构</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.require-once.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="function.include"
><A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
></A
></H1
><P
> <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 语句包含并运行指定文件。
</P
><P
> 以下文档也适用于
<A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
>。这两种结构除了在如何处理失败之外完全一样。<A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
>
产生一个<A
HREF="phpdevel-errors.html#internal.e-warning"
>警告</A
>而 <A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
> 则导致一个<A
HREF="phpdevel-errors.html#internal.e-error"
>致命错误</A
>。换句话说，如果想在遇到丢失文件时停止处理页面就用
<A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
>。<A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
>
就不是这样，脚本会继续运行。同时也要确认设置了合适的 <A
HREF="ini.core.html#ini.include-path"
>include_path</A
>。注意在
PHP 4.3.5 之前，包含文件中的语法错误不会导致程序停止，但从此版本之后会。
</P
><P
> 寻找包含文件的顺序先是在当前工作目录的相对的 include_path
下寻找，然后是当前运行脚本所在目录相对的 include_path 下寻找。例如
include_path 是 <TT
CLASS="literal"
>.</TT
>，当前工作目录是
<TT
CLASS="filename"
>/www/</TT
>，脚本中要 include 一个
<TT
CLASS="filename"
>include/a.php</TT
> 并且在该文件中有一句
<TT
CLASS="literal"
>include "b.php"</TT
>，则寻找
<TT
CLASS="filename"
>b.php</TT
> 的顺序先是
<TT
CLASS="filename"
>/www/</TT
>，然后是
<TT
CLASS="filename"
>/www/include/</TT
>。如果文件名以
<TT
CLASS="literal"
>./</TT
> 或者 <TT
CLASS="literal"
>../</TT
> 开始，则只在当前工作目录相对的
include_path 下寻找。
</P
><P
> 当一个文件被包含时，其中所包含的代码继承了 include 所在行的<A
HREF="language.variables.scope.html"
>变量范围</A
>。从该处开始，调用文件在该行处可用的任何变量在被调用的文件中也都可用。不过所有在包含文件中定义的函数和类都具有全局作用域。
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5114"
></A
><P
><B
>例 16-5. 基本的 <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 例子</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
vars.php<br /><font color="#0000BB"><?php<br /><br />$color </font><font color="#007700">= </font><font color="#DD0000">'green'</font><font color="#007700">;<br /></font><font color="#0000BB">$fruit </font><font color="#007700">= </font><font color="#DD0000">'apple'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />test.php<br /><font color="#0000BB"><?php<br /><br /></font><font color="#007700">echo </font><font color="#DD0000">"A $color $fruit"</font><font color="#007700">; </font><font color="#FF8000">// A<br /><br /></font><font color="#007700">include </font><font color="#DD0000">'vars.php'</font><font color="#007700">;<br /><br />echo </font><font color="#DD0000">"A $color $fruit"</font><font color="#007700">; </font><font color="#FF8000">// A green apple<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> 如果 include 出现于调用文件中的一个函数里，则被调用的文件中所包含的所有代码将表现得如同它们是在该函数内部定义的一样。所以它将遵循该函数的变量范围。
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5120"
></A
><P
><B
>例 16-6. 函数中的包含</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#007700">function </font><font color="#0000BB">foo</font><font color="#007700">()<br />{<br /> global </font><font color="#0000BB">$color</font><font color="#007700">;<br /><br /> include </font><font color="#DD0000">'vars.php'</font><font color="#007700">;<br /><br /> echo </font><font color="#DD0000">"A $color $fruit"</font><font color="#007700">;<br />}<br /><br /></font><font color="#FF8000">/* vars.php is in the scope of foo() so *<br /> * $fruit is NOT available outside of this *<br /> * scope. $color is because we declared it *<br /> * as global. */<br /><br /></font><font color="#0000BB">foo</font><font color="#007700">(); </font><font color="#FF8000">// A green apple<br /></font><font color="#007700">echo </font><font color="#DD0000">"A $color $fruit"</font><font color="#007700">; </font><font color="#FF8000">// A green<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> 当一个文件被包含时，语法解析器在目标文件的开头脱离 PHP 模式并进入 HTML
模式，到文件结尾处恢复。由于此原因，目标文件中应被当作
PHP 代码执行的任何代码都必须被包括在<A
HREF="language.basic-syntax.html#language.basic-syntax.phpmode"
>有效的 PHP 起始和结束标记</A
>之中。
</P
><P
> 如果“<A
HREF="ref.filesystem.html#ini.allow-url-fopen"
>URL fopen wrappers</A
>”在
PHP 中被激活（默认配置），可以用 URL（通过 HTTP
或者其它支持的封装协议――所支持的协议见<A
HREF="wrappers.html"
>附录 N</A
>）而不是本地文件来指定要被包含的文件。如果目标服务器将目标文件作为
PHP 代码解释，则可以用适用于 HTTP GET 的 URL
请求字符串来向被包括的文件传递变量。严格的说这和包含一个文件并继承父文件的变量空间并不是一回事；该脚本文件实际上已经在远程服务器上运行了，而本地脚本则包括了其结果。
</P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>警告</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>Windows 版本的 PHP
在 4.3.0 版之前不支持本函数的远程文件访问，即使
<A
HREF="ref.filesystem.html#ini.allow-url-fopen"
>allow_url_fopen</A
> 选项已被激活。</P
></TD
></TR
></TABLE
></DIV
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5132"
></A
><P
><B
>例 16-7. 通过 HTTP 进行的 <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#FF8000">/* This example assumes that www.example.com is configured to parse .php *<br /> * files and not .txt files. Also, 'Works' here means that the variables *<br /> * $foo and $bar are available within the included file. */<br /><br />// Won't work; file.txt wasn't handled by www.example.com as PHP<br /></font><font color="#007700">include </font><font color="#DD0000">'http://www.example.com/file.txt?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#FF8000">// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the<br />// local filesystem.<br /></font><font color="#007700">include </font><font color="#DD0000">'file.php?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#FF8000">// Works.<br /></font><font color="#007700">include </font><font color="#DD0000">'http://www.example.com/file.php?foo=1&bar=2'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">$foo </font><font color="#007700">= </font><font color="#0000BB">1</font><font color="#007700">;<br /></font><font color="#0000BB">$bar </font><font color="#007700">= </font><font color="#0000BB">2</font><font color="#007700">;<br />include </font><font color="#DD0000">'file.txt'</font><font color="#007700">; </font><font color="#FF8000">// Works.<br /></font><font color="#007700">include </font><font color="#DD0000">'file.php'</font><font color="#007700">; </font><font color="#FF8000">// Works.<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>安全警告</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
> 远程文件可能会经远程服务器处理（根据文件后缀以及远程服务器是否在运行
PHP 而定），但必须产生出一个合法的 PHP
脚本，因为其将被本地服务器处理。如果来自远程服务器的文件应该在远端运行而只输出结果，那用
<A
HREF="function.readfile.html"
><B
CLASS="function"
>readfile()</B
></A
>
函数更好。另外还要格外小心以确保远程的脚本产生出合法并且是所需的代码。
</P
></TD
></TR
></TABLE
></DIV
><P
> 相关信息参见<A
HREF="features.remote-files.html"
>使用远程文件</A
>，<A
HREF="function.fopen.html"
><B
CLASS="function"
>fopen()</B
></A
>
和 <A
HREF="function.file.html"
><B
CLASS="function"
>file()</B
></A
>。
</P
><P
> 因为 <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 和 <A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
>
是特殊的语言结构，在条件语句中使用必须将其放在语句组中（花括号中）。
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5148"
></A
><P
><B
>例 16-8. include() 与条件语句组</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /><br /></font><font color="#FF8000">// This is WRONG and will not work as desired.<br /></font><font color="#007700">if (</font><font color="#0000BB">$condition</font><font color="#007700">)<br /> include </font><font color="#0000BB">$file</font><font color="#007700">;<br />else<br /> include </font><font color="#0000BB">$other</font><font color="#007700">;<br /><br /><br /></font><font color="#FF8000">// This is CORRECT.<br /></font><font color="#007700">if (</font><font color="#0000BB">$condition</font><font color="#007700">) {<br /> include </font><font color="#0000BB">$file</font><font color="#007700">;<br />} else {<br /> include </font><font color="#0000BB">$other</font><font color="#007700">;<br />}<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> 处理返回值：可以在被包括的文件中使用 <A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
>
语句来终止该文件中程序的执行并返回调用它的脚本。同样也可以从被包含的文件中返回值。可以像普通函数一样获得
include 调用的返回值。不过这在包含远程文件时却不行，除非远程文件的输出具有<A
HREF="language.basic-syntax.html#language.basic-syntax.phpmode"
>合法的 PHP
开始和结束标记</A
>（如同任何本地文件一样）。可以在标记内定义所需的变量，该变量在文件被包含的位置之后就可用了。
</P
><P
> 因为 <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 是一个特殊的语言结构，其参数不需要括号。在比较其返回值时要注意。
<TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5156"
></A
><P
><B
>例 16-9. 比较 include 的返回值</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br /></font><font color="#FF8000">// won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')<br /></font><font color="#007700">if (include(</font><font color="#DD0000">'vars.php'</font><font color="#007700">) == </font><font color="#DD0000">'OK'</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">'OK'</font><font color="#007700">;<br />}<br /><br /></font><font color="#FF8000">// works<br /></font><font color="#007700">if ((include </font><font color="#DD0000">'vars.php'</font><font color="#007700">) == </font><font color="#DD0000">'OK'</font><font color="#007700">) {<br /> echo </font><font color="#DD0000">'OK'</font><font color="#007700">;<br />}<br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
在 PHP 3 中，除非是在函数中调用否则被包含的文件中不能出现
return。在此情况下 <A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
> 作用于该函数而不是整个文件。
</P
></BLOCKQUOTE
></DIV
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5163"
></A
><P
><B
>例 16-10. <A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 和 <A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
> 语句</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
return.php<br /><font color="#0000BB"><?php<br /><br />$var </font><font color="#007700">= </font><font color="#DD0000">'PHP'</font><font color="#007700">;<br /><br />return </font><font color="#0000BB">$var</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />noreturn.php<br /><font color="#0000BB"><?php<br /><br />$var </font><font color="#007700">= </font><font color="#DD0000">'PHP'</font><font color="#007700">;<br /><br /></font><font color="#0000BB">?><br /></font><br />testreturns.php<br /><font color="#0000BB"><?php<br /><br />$foo </font><font color="#007700">= include </font><font color="#DD0000">'return.php'</font><font color="#007700">;<br /><br />echo </font><font color="#0000BB">$foo</font><font color="#007700">; </font><font color="#FF8000">// prints 'PHP'<br /><br /></font><font color="#0000BB">$bar </font><font color="#007700">= include </font><font color="#DD0000">'noreturn.php'</font><font color="#007700">;<br /><br />echo </font><font color="#0000BB">$bar</font><font color="#007700">; </font><font color="#FF8000">// prints 1<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> <TT
CLASS="literal"
>$bar</TT
> 的值为 <TT
CLASS="literal"
>1</TT
> 是因为 include
成功运行了。注意以上例子中的区别。第一个在被包含的文件中用了
<A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
> 而另一个没有。如果文件不能被包含，则返回
<TT
CLASS="constant"
><B
>FALSE</B
></TT
> 并发出一个 <TT
CLASS="literal"
>E_WARNING</TT
> 警告。
</P
><P
> 如果在包含文件中定义有函数，这些函数可以独立于是否在
<A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
> 之前还是之后在主文件中使用。如果文件被包含两次，PHP
5 发出致命错误因为函数已经被定义，但是 PHP 在
<A
HREF="function.return.html"
><B
CLASS="function"
>return()</B
></A
> 之后不会抱怨函数已定义。推荐使用
<A
HREF="function.include-once.html"
><B
CLASS="function"
>include_once()</B
></A
> 而不是检查文件是否已包含并在包含文件中有条件返回。
</P
><P
> 另一个将 PHP 文件“包含”到一个变量中的方法是用<A
HREF="ref.outcontrol.html"
>输出控制函数</A
>结合
<A
HREF="function.include.html"
><B
CLASS="function"
>include()</B
></A
> 来捕获其输出，例如：
</P
><P
> <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN5182"
></A
><P
><B
>例 16-11. 使用输出缓冲来将 PHP 文件包含入一个字符串</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><code><font color="#000000">
<font color="#0000BB"><?php<br />$string </font><font color="#007700">= </font><font color="#0000BB">get_include_contents</font><font color="#007700">(</font><font color="#DD0000">'somefile.php'</font><font color="#007700">);<br /><br />function </font><font color="#0000BB">get_include_contents</font><font color="#007700">(</font><font color="#0000BB">$filename</font><font color="#007700">) {<br /> if (</font><font color="#0000BB">is_file</font><font color="#007700">(</font><font color="#0000BB">$filename</font><font color="#007700">)) {<br /> </font><font color="#0000BB">ob_start</font><font color="#007700">();<br /> include </font><font color="#0000BB">$filename</font><font color="#007700">;<br /> </font><font color="#0000BB">$contents </font><font color="#007700">= </font><font color="#0000BB">ob_get_contents</font><font color="#007700">();<br /> </font><font color="#0000BB">ob_end_clean</font><font color="#007700">();<br /> return </font><font color="#0000BB">$contents</font><font color="#007700">;<br /> }<br /> return </font><font color="#0000BB">false</font><font color="#007700">;<br />}<br /><br /></font><font color="#0000BB">?></font>
</font>
</code></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
</P
><P
> 要在脚本中自动包含文件，参见 <TT
CLASS="filename"
>php.ini</TT
> 中的
<A
HREF="ini.core.html#ini.auto-prepend-file"
>auto_prepend_file</A
> 和
<A
HREF="ini.core.html#ini.auto-append-file"
>auto_append_file</A
>
配置选项。
</P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>由于这是一个语言结构而非函数，因此它无法被<A
HREF="functions.variable-functions.html"
>变量函数</A
>调用。</P
></BLOCKQUOTE
></DIV
><P
> 参见 <A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
>，<A
HREF="function.require-once.html"
><B
CLASS="function"
>require_once()</B
></A
>，<A
HREF="function.include-once.html"
><B
CLASS="function"
>include_once()</B
></A
>，<A
HREF="function.get-included-files.html"
><B
CLASS="function"
>get_included_files()</B
></A
>，<A
HREF="function.readfile.html"
><B
CLASS="function"
>readfile()</B
></A
>，<A
HREF="function.virtual.html"
><B
CLASS="function"
>virtual()</B
></A
> 和 <A
HREF="ini.core.html#ini.include-path"
>include_path</A
>。
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.require.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>起始页</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.require-once.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.require.html"
><B
CLASS="function"
>require()</B
></A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="language.control-structures.html"
ACCESSKEY="U"
>上一级</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.require-once.html"
><B
CLASS="function"
>require_once()</B
></A
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
