mirror of
https://github.com/php/doc-zh.git
synced 2026-03-25 07:32:10 +01:00
292 lines
10 KiB
XML
292 lines
10 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- $Revision$ -->
|
||
<!-- EN-Revision: a124543dd3f6b1e5567b07420d23899e582514dc Maintainer: dallas Status: ready -->
|
||
<!-- CREDITS: Luffy -->
|
||
<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
<title>include</title>
|
||
<?phpdoc print-version-for="include"?>
|
||
<simpara>
|
||
<literal>include</literal> 表达式包含并运行指定文件。
|
||
</simpara>
|
||
<simpara>
|
||
以下文档也适用于 <function>require</function>。
|
||
</simpara>
|
||
<simpara>
|
||
被包含文件先按参数给出的路径寻找，如果没有给出目录（只有文件名）时则按照
|
||
<link linkend="ini.include-path">include_path</link> 指定的目录寻找。如果在
|
||
<link linkend="ini.include-path">include_path</link> 下没找到该文件则
|
||
<literal>include</literal> 最后才在调用脚本文件所在的目录和当前工作目录下寻找。如果最后仍未找到文件则
|
||
<literal>include</literal> 结构会发出一条 <constant>E_WARNING</constant> ；这一点和
|
||
<function>require</function> 不同，后者会发出一个 <constant>E_ERROR</constant> 。
|
||
</simpara>
|
||
<simpara>
|
||
注意如果文件无法访问， <literal>include</literal> 和 <literal>require</literal>
|
||
在分别发出最后的 <constant>E_WARNING</constant> 或 <constant>E_ERROR</constant>
|
||
之前，都会发出额外一条 <constant>E_WARNING</constant>。
|
||
</simpara>
|
||
<simpara>
|
||
如果定义了路径——不管是绝对路径（在 Windows
|
||
下以盘符或者 <literal>\</literal> 开头，在 Unix/Linux
|
||
下以 <literal>/</literal> 开头）还是当前目录的相对路径（以
|
||
<literal>.</literal> 或者 <literal>..</literal> 开头）——<link
|
||
linkend="ini.include-path">include_path</link> 都会被完全忽略。例如一个文件以
|
||
<literal>../</literal> 开头，则解析器会在当前目录的父目录下寻找该文件。
|
||
</simpara>
|
||
<simpara>
|
||
有关 PHP 怎样处理包含文件和包含路径的更多信息参见
|
||
<link linkend="ini.include-path">include_path</link> 部分的文档。
|
||
</simpara>
|
||
<simpara>
|
||
当一个文件被包含时，其中所包含的代码继承了 include 所在行的<link
|
||
linkend="language.variables.scope">变量范围</link>。从该处开始，调用文件在该行处可用的任何变量在被调用的文件中也都可用。不过所有在包含文件中定义的函数和类都具有全局作用域。
|
||
</simpara>
|
||
<para>
|
||
<example>
|
||
<title>基本的 <literal>include</literal> 例子</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
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
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<simpara>
|
||
如果 include 出现于调用文件中的一个函数里，则被调用的文件中所包含的所有代码将表现得如同它们是在该函数内部定义的一样。所以它将遵循该函数的变量范围。此规则的一个例外是<link
|
||
linkend="language.constants.magic">魔术常量</link>，它们是在发生包含之前就已被解析器处理的。
|
||
</simpara>
|
||
<para>
|
||
<example>
|
||
<title>函数中的包含</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
function foo()
|
||
{
|
||
global $color;
|
||
|
||
include 'vars.php';
|
||
|
||
echo "A $color $fruit";
|
||
}
|
||
|
||
/* vars.php 在 foo() 范围内，所以 $fruit 在范围为不可用。 *
|
||
* $color 能用是因为声明成全局变量。 */
|
||
|
||
foo(); // A green apple
|
||
echo "A $color $fruit"; // A green
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<simpara>
|
||
当一个文件被包含时，语法解析器在目标文件的开头脱离 PHP 模式并进入 HTML
|
||
模式，到文件结尾处恢复。由于此原因，目标文件中需要作为
|
||
PHP 代码执行的任何代码都必须被包括在<link
|
||
linkend="language.basic-syntax.phpmode">有效的 PHP 起始和结束标记</link>之中。
|
||
</simpara>
|
||
<simpara>
|
||
如果“<link linkend="ini.allow-url-include">URL include wrappers</link>”在
|
||
PHP 中被激活，可以用 URL（通过 HTTP
|
||
或者其它支持的封装协议——见<xref linkend="wrappers"/>）而不是本地文件来指定要被包含的文件。如果目标服务器将目标文件作为
|
||
PHP 代码解释，则可以用适用于 HTTP GET 的 URL
|
||
请求字符串来向被包括的文件传递变量。严格的说这和包含一个文件并继承父文件的变量空间并不是一回事；该脚本文件实际上已经在远程服务器上运行了，而本地脚本则包括了其结果。
|
||
</simpara>
|
||
<para>
|
||
<example>
|
||
<title>通过 HTTP 进行的 <literal>include</literal></title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
/* 这个示例假定 www.example.com 配置为解析 .php 文件而不解析 .txt 文件。 *
|
||
* 此外 “Works” 意味着 $foo 和 $bar 变量在包含的文件中是可用的。 */
|
||
|
||
// 无法执行； file.txt 没有被 www.example.com 当作 PHP 处理。
|
||
include 'http://www.example.com/file.txt?foo=1&bar=2';
|
||
|
||
// 无法执行；在本地文件系统中查找名为 “file.php?foo=1&bar=2” 的文件。
|
||
include 'file.php?foo=1&bar=2';
|
||
|
||
// 正常。
|
||
include 'http://www.example.com/file.php?foo=1&bar=2';
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<warning>
|
||
<title>安全警告</title>
|
||
<para>
|
||
远程文件可能会经远程服务器处理（根据文件后缀以及远程服务器是否在运行
|
||
PHP 而定），但必须产生出一个合法的 PHP
|
||
脚本，因为其将被本地服务器处理。如果来自远程服务器的文件应该在远端运行而只输出结果，那用
|
||
<function>readfile</function>
|
||
函数更好。另外还要格外小心以确保远程的脚本产生出合法并且是所需的代码。
|
||
</para>
|
||
</warning>
|
||
<para>
|
||
相关信息参见<link
|
||
linkend="features.remote-files">使用远程文件</link>，<function>fopen</function>
|
||
和 <function>file</function>。
|
||
</para>
|
||
<simpara>
|
||
处理返回值：在失败时 <literal>include</literal> 返回 <literal>FALSE</literal>
|
||
并且发出警告。成功的包含则返回
|
||
<literal>1</literal>，除非在包含文件中另外给出了返回值。可以在被包括的文件中使用 <function>return</function>
|
||
语句来终止该文件中程序的执行并返回调用它的脚本。同样也可以从被包含的文件中返回值。可以像普通函数一样获得
|
||
include 调用的返回值。不过这在包含远程文件时却不行，除非远程文件的输出具有<link
|
||
linkend="language.basic-syntax.phpmode">合法的 PHP
|
||
开始和结束标记</link>（如同任何本地文件一样）。可以在标记内定义所需的变量，该变量在文件被包含的位置之后就可用了。
|
||
</simpara>
|
||
<para>
|
||
因为 <literal>include</literal> 是一个特殊的语言结构，其参数不需要括号。在比较其返回值时要注意。
|
||
<example>
|
||
<title>比较 include 的返回值</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
// 不能运行，执行 include(('vars.php') == TRUE) 就等于执行 include('1')
|
||
if (include('vars.php') == TRUE) {
|
||
echo 'OK';
|
||
}
|
||
|
||
// 正常
|
||
if ((include 'vars.php') == TRUE) {
|
||
echo 'OK';
|
||
}
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title><literal>include</literal> 和 <function>return</function> 语句</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
return.php
|
||
<?php
|
||
|
||
$var = 'PHP';
|
||
|
||
return $var;
|
||
|
||
?>
|
||
|
||
noreturn.php
|
||
<?php
|
||
|
||
$var = 'PHP';
|
||
|
||
?>
|
||
|
||
testreturns.php
|
||
<?php
|
||
|
||
$foo = include 'return.php';
|
||
|
||
echo $foo; // 打印 'PHP'
|
||
|
||
$bar = include 'noreturn.php';
|
||
|
||
echo $bar; // 打印 1
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<simpara>
|
||
<literal>$bar</literal> 的值为 <literal>1</literal> 是因为 include
|
||
成功运行了。注意以上例子中的区别。第一个在被包含的文件中用了
|
||
<function>return</function> 而另一个没有。如果文件不能被包含，则返回
|
||
&false; 并发出一个 <constant>E_WARNING</constant> 警告。
|
||
</simpara>
|
||
<para>
|
||
如果在包含文件中定义了函数，无论是在 <function>return</function>
|
||
之前还是之后，都可以独立在主文件（main）中使用。如果文件被包含两次，由于函数重复定义，PHP 会
|
||
发出致命错误（fatal error）。推荐使用 <function>include_once</function>
|
||
而不是检查文件是否已包含并在包含文件中有条件返回。
|
||
</para>
|
||
<simpara>
|
||
另一个将 PHP 文件“包含”到一个变量中的方法是用<link
|
||
linkend="ref.outcontrol">输出控制函数</link>结合
|
||
<function>include</function> 来捕获其输出，例如：
|
||
</simpara>
|
||
<para>
|
||
<example>
|
||
<title>使用输出缓冲来将 PHP 文件包含入一个字符串</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
$string = get_include_contents('somefile.php');
|
||
|
||
function get_include_contents($filename) {
|
||
if (is_file($filename)) {
|
||
ob_start();
|
||
include $filename;
|
||
$contents = ob_get_contents();
|
||
ob_end_clean();
|
||
return $contents;
|
||
}
|
||
return false;
|
||
}
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
要在脚本中自动包含文件，参见 &php.ini; 中的
|
||
<link linkend="ini.auto-prepend-file">auto_prepend_file</link> 和
|
||
<link linkend="ini.auto-append-file">auto_append_file</link>
|
||
配置选项。
|
||
</para>
|
||
¬e.language-construct;
|
||
<simpara>
|
||
参见 <function>require</function>、<function>require_once</function>、<function>include_once</function>、<function>get_included_files</function>、<function>readfile</function>、<function>virtual</function>、<link linkend="ini.include-path">include_path</link>。
|
||
</simpara>
|
||
</sect1>
|
||
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
-->
|