include

(PHP 4, PHP 5, PHP 7, PHP 8)

include 表達(dá)式包含并運(yùn)行指定文件。

以下文檔也適用于 require。

被包含文件先按參數(shù)給出的路徑尋找，如果沒(méi)有給出目錄（只有文件名）時(shí)則按照 include_path 指定的目錄尋找。如果在 include_path 下沒(méi)找到該文件則 include 最后才在調(diào)用腳本文件所在的目錄和當(dāng)前工作目錄下尋找。如果最后仍未找到文件則 include 結(jié)構(gòu)會(huì)發(fā)出一條 E_WARNING ；這一點(diǎn)和 require 不同，后者會(huì)發(fā)出一個(gè) E_ERROR 。

注意如果文件無(wú)法訪問(wèn)， include 和 require 在分別發(fā)出最后的 E_WARNING 或 E_ERROR 之前，都會(huì)發(fā)出額外一條 E_WARNING。

如果定義了路徑——不管是絕對(duì)路徑（在 Windows 下以盤符或者 \ 開(kāi)頭，在 Unix/Linux 下以 / 開(kāi)頭）還是當(dāng)前目錄的相對(duì)路徑（以 . 或者 .. 開(kāi)頭）——include_path 都會(huì)被完全忽略。例如一個(gè)文件以 ../ 開(kāi)頭，則解析器會(huì)在當(dāng)前目錄的父目錄下尋找該文件。

有關(guān) PHP 怎樣處理包含文件和包含路徑的更多信息參見(jiàn) include_path 部分的文檔。

當(dāng)一個(gè)文件被包含時(shí)，其中所包含的代碼繼承了 include 所在行的變量范圍。從該處開(kāi)始，調(diào)用文件在該行處可用的任何變量在被調(diào)用的文件中也都可用。不過(guò)所有在包含文件中定義的函數(shù)和類都具有全局作用域。

示例 #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 出現(xiàn)于調(diào)用文件中的一個(gè)函數(shù)里，則被調(diào)用的文件中所包含的所有代碼將表現(xiàn)得如同它們是在該函數(shù)內(nèi)部定義的一樣。所以它將遵循該函數(shù)的變量范圍。此規(guī)則的一個(gè)例外是魔術(shù)常量，它們是在發(fā)生包含之前就已被解析器處理的。

示例 #2 函數(shù)中的包含


<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php 在 foo() 范圍內(nèi)，所以 $fruit 在范圍為不可用。 *
 * $color 能用是因?yàn)槁暶鞒扇肿兞俊?nbsp;*/

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

?>

當(dāng)一個(gè)文件被包含時(shí)，語(yǔ)法解析器在目標(biāo)文件的開(kāi)頭脫離 PHP 模式并進(jìn)入 HTML 模式，到文件結(jié)尾處恢復(fù)。由于此原因，目標(biāo)文件中需要作為 PHP 代碼執(zhí)行的任何代碼都必須被包括在有效的 PHP 起始和結(jié)束標(biāo)記之中。

如果“URL include wrappers”在 PHP 中被激活，可以用 URL（通過(guò) HTTP 或者其它支持的封裝協(xié)議——見(jiàn)支持的協(xié)議和封裝協(xié)議）而不是本地文件來(lái)指定要被包含的文件。如果目標(biāo)服務(wù)器將目標(biāo)文件作為 PHP 代碼解釋，則可以用適用于 HTTP GET 的 URL 請(qǐng)求字符串來(lái)向被包括的文件傳遞變量。嚴(yán)格的說(shuō)這和包含一個(gè)文件并繼承父文件的變量空間并不是一回事；該腳本文件實(shí)際上已經(jīng)在遠(yuǎn)程服務(wù)器上運(yùn)行了，而本地腳本則包括了其結(jié)果。

示例 #3 通過(guò) HTTP 進(jìn)行的 include


<?php

/* 這個(gè)示例假定 www.example.com 配置為解析 .php 文件而不解析 .txt 文件。 *
 * 此外 “Works” 意味著 $foo 和 $bar 變量在包含的文件中是可用的。         */

// 無(wú)法執(zhí)行； file.txt 沒(méi)有被 www.example.com 當(dāng)作 PHP 處理。
include 'http://www.example.com/file.txt?foo=1&bar=2';

// 無(wú)法執(zhí)行；在本地文件系統(tǒng)中查找名為 “file.php?foo=1&bar=2” 的文件。
include 'file.php?foo=1&bar=2';

// 正常。
include 'http://www.example.com/file.php?foo=1&bar=2';
?>

警告

安全警告

遠(yuǎn)程文件可能會(huì)經(jīng)遠(yuǎn)程服務(wù)器處理（根據(jù)文件后綴以及遠(yuǎn)程服務(wù)器是否在運(yùn)行 PHP 而定），但必須產(chǎn)生出一個(gè)合法的 PHP 腳本，因?yàn)槠鋵⒈槐镜胤?wù)器處理。如果來(lái)自遠(yuǎn)程服務(wù)器的文件應(yīng)該在遠(yuǎn)端運(yùn)行而只輸出結(jié)果，那用 readfile() 函數(shù)更好。另外還要格外小心以確保遠(yuǎn)程的腳本產(chǎn)生出合法并且是所需的代碼。

相關(guān)信息參見(jiàn)使用遠(yuǎn)程文件，fopen() 和 file()。

處理返回值：在失敗時(shí) include 返回 FALSE 并且發(fā)出警告。成功的包含則返回 1，除非在包含文件中另外給出了返回值?？梢栽诒话ǖ奈募惺褂?return 語(yǔ)句來(lái)終止該文件中程序的執(zhí)行并返回調(diào)用它的腳本。同樣也可以從被包含的文件中返回值?？梢韵衿胀ê瘮?shù)一樣獲得 include 調(diào)用的返回值。不過(guò)這在包含遠(yuǎn)程文件時(shí)卻不行，除非遠(yuǎn)程文件的輸出具有合法的 PHP 開(kāi)始和結(jié)束標(biāo)記（如同任何本地文件一樣）?？梢栽跇?biāo)記內(nèi)定義所需的變量，該變量在文件被包含的位置之后就可用了。

因?yàn)?include 是一個(gè)特殊的語(yǔ)言結(jié)構(gòu)，其參數(shù)不需要括號(hào)。在比較其返回值時(shí)要注意。

示例 #4 比較 include 的返回值


<?php
// 不能運(yùn)行，執(zhí)行 include(('vars.php') == TRUE) 就等于執(zhí)行 include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// 正常
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>

示例 #5 include 和 return 語(yǔ)句


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

?>

$bar 的值為 1 是因?yàn)?include 成功運(yùn)行了。注意以上例子中的區(qū)別。第一個(gè)在被包含的文件中用了 return 而另一個(gè)沒(méi)有。如果文件不能被包含，則返回 false 并發(fā)出一個(gè) E_WARNING 警告。

如果在包含文件中定義了函數(shù)，無(wú)論是在 return 之前還是之后，都可以獨(dú)立在主文件（main）中使用。如果文件被包含兩次，由于函數(shù)重復(fù)定義，PHP 會(huì) 發(fā)出致命錯(cuò)誤（fatal error）。推薦使用 include_once 而不是檢查文件是否已包含并在包含文件中有條件返回。

另一個(gè)將 PHP 文件“包含”到一個(gè)變量中的方法是用輸出控制函數(shù)結(jié)合 include 來(lái)捕獲其輸出，例如：

示例 #6 使用輸出緩沖來(lái)將 PHP 文件包含入一個(gè)字符串


<?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;
}

?>

要在腳本中自動(dòng)包含文件，參見(jiàn) php.ini 中的 auto_prepend_file 和 auto_append_file 配置選項(xiàng)。

注意: 因?yàn)槭且粋€(gè)語(yǔ)言構(gòu)造器而不是一個(gè)函數(shù)，不能被可變函數(shù) 調(diào)用。

參見(jiàn) require、require_once、include_once、 get_included_files()、readfile()、virtual()、 include_path。