require

require?和?include?幾乎完全一樣，除了處理失敗的方式不同之外。?require?在出錯(cuò)時(shí)產(chǎn)生?E_COMPILE_ERROR?級(jí)別的錯(cuò)誤，換句話說(shuō)將導(dǎo)致腳本中止而?include?只產(chǎn)生警告（E_WARNING），腳本會(huì)繼續(xù)運(yùn)行。

include

include?語(yǔ)句包含并運(yùn)行指定文件。

以下文檔也適用于?require：

被包含文件先按參數(shù)給出的路徑尋找，如果沒(méi)有給出目錄（只有文件名）時(shí)則按照?include_path?指定的目錄尋找。如果在?include_path?下沒(méi)找到該文件則?include?最后才在調(diào)用腳本文件所在的目錄和當(dāng)前工作目錄下尋找。如果最后仍未找到文件則?include?結(jié)構(gòu)會(huì)發(fā)出一條警告；這一點(diǎn)和?require?不同，后者會(huì)發(fā)出一個(gè)致命錯(cuò)誤。（關(guān)于include_path可參考這篇文章：PHP擴(kuò)展之選項(xiàng)和配置信息）

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

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

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

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

<?phpfunction 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 appleecho 'A $color $fruit'; // A green?>

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

如果“URL fopen wrappers”在 PHP 中被激活（默認(rèn)配置），可以用 URL（通過(guò) HTTP 或者其它支持的封裝協(xié)議——見支持的協(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é)果。

WarningWindows 版本的 PHP 在 4.3.0 版之前不支持通過(guò)此函數(shù)訪問(wèn)遠(yuǎn)程文件，即使已經(jīng)啟用?allow_url_fopen.

Example #3 通過(guò) HTTP 進(jìn)行的?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.?>安全警告

遠(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)生出合法并且是所需的代碼。

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

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

Example #4 比較 include 的返回值

<?php//?won’t?work,?evaluated?as?include((’vars.php’)?==?’OK’),?i.e.?include(’’)if?(include(’vars.php’)?==?’OK’)?{????echo?’OK’;}//?worksif?((include?’vars.php’)?==?’OK’)?{????echo?’OK’;}?>

Example #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;?//?prints?’PHP’$bar?=?include?’noreturn.php’;echo?$bar;?//?prints?1?>

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

如果在包含文件中定義有函數(shù)，這些函數(shù)不管是在?return?之前還是之后定義的，都可以獨(dú)立在主文件中使用。如果文件被包含兩次，PHP 5 發(fā)出致命錯(cuò)誤因?yàn)楹瘮?shù)已經(jīng)被定義，但是 PHP 4 不會(huì)對(duì)在?return?之后定義的函數(shù)報(bào)錯(cuò)。推薦使用?include_once?而不是檢查文件是否已包含并在包含文件中有條件返回。

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

Example #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)包含文件，參見?php.ini?中的?auto_prepend_file?和?auto_append_file?配置選項(xiàng)。

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

require_once

(PHP 4, PHP 5)

require_once?語(yǔ)句和?require?語(yǔ)句完全相同，唯一區(qū)別是 PHP 會(huì)檢查該文件是否已經(jīng)被包含過(guò)，如果是則不會(huì)再次包含

include_once

(PHP 4, PHP 5)

include_once?語(yǔ)句在腳本執(zhí)行期間包含并運(yùn)行指定文件。此行為和?include?語(yǔ)句類似，唯一區(qū)別是如果該文件中已經(jīng)被包含過(guò)，則不會(huì)再次包含。如同此語(yǔ)句名字暗示的那樣，只會(huì)包含一次。

include_once?可以用于在腳本執(zhí)行期間同一個(gè)文件有可能被包含超過(guò)一次的情況下，想確保它只被包含一次以避免函數(shù)重定義，變量重新賦值等問(wèn)題。

Note:

在 PHP 4中，_once?的行為在不區(qū)分大小寫字母的操作系統(tǒng)（例如 Windows）中有所不同，例如：

Example #1?include_once?在 PHP 4 運(yùn)行于不區(qū)分大小寫的操作系統(tǒng)中

<?phpinclude_once?'a.php';?//?這將包含?a.phpinclude_once?'A.php';?//?這將再次包含?a.php?。▋H?PHP?4）?>

此行為在 PHP 5 中改了，例如在 Windows 中路徑先被規(guī)格化，因此?C:PROGRA~1A.php?和?C:Program Filesa.php?的實(shí)現(xiàn)一樣，文件只會(huì)被包含一次。