include · PHP之旅

## **include** (PHP 4, PHP 5, PHP 7) *include* 語句包含并運行指定文件。以下文檔也適用于 [require](http://php.net/manual/zh/function.require.php)。被包含文件先按參數給出的路徑尋找，如果沒有給出目錄（只有文件名）時則按照 [include\_path](http://php.net/manual/zh/ini.core.php#ini.include-path) 指定的目錄尋找。如果在 [include\_path](http://php.net/manual/zh/ini.core.php#ini.include-path) 下沒找到該文件則 *include* 最后才在調用腳本文件所在的目錄和當前工作目錄下尋找。如果最后仍未找到文件則 *include* 結構會發出一條[警告](http://php.net/manual/zh/errorfunc.constants.php#errorfunc.constants.errorlevels)；這一點和 [require](http://php.net/manual/zh/function.require.php) 不同，后者會發出一個[致命錯誤](http://php.net/manual/zh/errorfunc.constants.php#errorfunc.constants.errorlevels)。如果定義了路徑——不管是絕對路徑（在 Windows 下以盤符或者 *\\* 開頭，在 Unix/Linux 下以 */* 開頭）還是當前目錄的相對路徑（以 *.* 或者 *..* 開頭）——[include\_path](http://php.net/manual/zh/ini.core.php#ini.include-path) 都會被完全忽略。例如一個文件以 *../* 開頭，則解析器會在當前目錄的父目錄下尋找該文件。有關 PHP 怎樣處理包含文件和包含路徑的更多信息參見 [include\_path](http://php.net/manual/zh/ini.core.php#ini.include-path) 部分的文檔。當一個文件被包含時，其中所包含的代碼繼承了 include 所在行的[變量范圍](http://php.net/manual/zh/language.variables.scope.php)。從該處開始，調用文件在該行處可用的任何變量在被調用的文件中也都可用。不過所有在包含文件中定義的函數和類都具有全局作用域。 **Example #1 基本的 *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 出現于調用文件中的一個函數里，則被調用的文件中所包含的所有代碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變量范圍。此規則的一個例外是[魔術常量](http://php.net/manual/zh/language.constants.predefined.php)，它們是在發生包含之前就已被解析器處理的。 **Example #2 函數中的包含** ``` <?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 起始和結束標記](http://php.net/manual/zh/language.basic-syntax.phpmode.php)之中。如果“[URL fopen wrappers](http://php.net/manual/zh/filesystem.configuration.php#ini.allow-url-fopen)”在 PHP 中被激活（默認配置），可以用 URL（通過 HTTP 或者其它支持的封裝協議——見[支持的協議和封裝協議](http://php.net/manual/zh/wrappers.php)）而不是本地文件來指定要被包含的文件。如果目標服務器將目標文件作為 PHP 代碼解釋，則可以用適用于 HTTP GET 的 URL 請求字符串來向被包括的文件傳遞變量。嚴格的說這和包含一個文件并繼承父文件的變量空間并不是一回事；該腳本文件實際上已經在遠程服務器上運行了，而本地腳本則包括了其結果。 **Warning** Windows 版本的 PHP 在 4.3.0 版之前不支持通過此函數訪問遠程文件，即使已經啟用 [allow\_url\_fopen](http://php.net/manual/zh/filesystem.configuration.php#ini.allow-url-fopen). **Example #3 通過 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. ?> ``` **Warning** # 安全警告遠程文件可能會經遠程服務器處理（根據文件后綴以及遠程服務器是否在運行 PHP 而定），但必須產生出一個合法的 PHP 腳本，因為其將被本地服務器處理。如果來自遠程服務器的文件應該在遠端運行而只輸出結果，那用 [readfile()](http://php.net/manual/zh/function.readfile.php) 函數更好。另外還要格外小心以確保遠程的腳本產生出合法并且是所需的代碼。相關信息參見[使用遠程文件](http://php.net/manual/zh/features.remote-files.php)，[fopen()](http://php.net/manual/zh/function.fopen.php) 和 [file()](http://php.net/manual/zh/function.file.php)。處理返回值：在失敗時 *include* 返回 *FALSE* 并且發出警告。成功的包含則返回 *1*，除非在包含文件中另外給出了返回值。可以在被包括的文件中使用 [return](http://php.net/manual/zh/function.return.php) 語句來終止該文件中程序的執行并返回調用它的腳本。同樣也可以從被包含的文件中返回值。可以像普通函數一樣獲得 include 調用的返回值。不過這在包含遠程文件時卻不行，除非遠程文件的輸出具有[合法的 PHP 開始和結束標記](http://php.net/manual/zh/language.basic-syntax.phpmode.php)（如同任何本地文件一樣）。可以在標記內定義所需的變量，該變量在文件被包含的位置之后就可用了。因為 *include* 是一個特殊的語言結構，其參數不需要括號。在比較其返回值時要注意。 **Example #4 比較 include 的返回值** ``` <?php //?won't?work,?evaluated?as?include(('vars.php')?==?'OK'),?i.e.?include('') if?(include('vars.php')?==?'OK')?{ ????echo?'OK'; } //?works if?((include?'vars.php')?==?'OK')?{ ????echo?'OK'; } ?> ``` **Example #5 *include* 和 **[**return**](http://php.net/manual/zh/function.return.php)** 語句** ``` 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](http://php.net/manual/zh/function.return.php) 而另一個沒有。如果文件不能被包含，則返回 **`FALSE**` 并發出一個 **`E_WARNING**` 警告。如果在包含文件中定義有函數，這些函數不管是在 [return](http://php.net/manual/zh/function.return.php) 之前還是之后定義的，都可以獨立在主文件中使用。如果文件被包含兩次，PHP 5 發出致命錯誤因為函數已經被定義，但是 PHP 4 不會對在 [return](http://php.net/manual/zh/function.return.php) 之后定義的函數報錯。推薦使用 [include\_once](http://php.net/manual/zh/function.include-once.php) 而不是檢查文件是否已包含并在包含文件中有條件返回。另一個將 PHP 文件“包含”到一個變量中的方法是用[輸出控制函數](http://php.net/manual/zh/ref.outcontrol.php)結合 **include** 來捕獲其輸出，例如： **Example #6 使用輸出緩沖來將 PHP 文件包含入一個字符串** ``` <?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; } ?> ``` 要在腳本中自動包含文件，參見 php.ini 中的 [auto\_prepend\_file](http://php.net/manual/zh/ini.core.php#ini.auto-prepend-file) 和 [auto\_append\_file](http://php.net/manual/zh/ini.core.php#ini.auto-append-file) 配置選項。 > **Note**: 因為是一個語言構造器而不是一個函數，不能被 [可變函數](http://php.net/manual/zh/functions.variable-functions.php) 調用。參見 [require](http://php.net/manual/zh/function.require.php)，[require\_once](http://php.net/manual/zh/function.require-once.php)，[include\_once](http://php.net/manual/zh/function.include-once.php)，[get\_included\_files()](http://php.net/manual/zh/function.get-included-files.php)，[readfile()](http://php.net/manual/zh/function.readfile.php)，[virtual()](http://php.net/manual/zh/function.virtual.php) 和 [include\_path](http://php.net/manual/zh/ini.core.php#ini.include-path)。