(PHP 4, PHP 5, PHP 7, PHP 8)
include 表達式包含并運行指定文件。
以下文檔也適用于 require。
被包含文件先按參數給出的路徑尋找，如果沒(méi)有給出目錄（只有文件名）時(shí)則按照
include_path 指定的目錄尋找。如果在
include_path 下沒(méi)找到該文件則
include 最后才在調用腳本文件所在的目錄和當前工作目錄下尋找。如果最后仍未找到文件則
include 結構會(huì )發(fā)出一條 E_WARNING ；這一點(diǎn)和
require 不同，后者會(huì )發(fā)出一個(gè) E_ERROR 。
注意如果文件無(wú)法訪(fǎng)問(wèn)， include 和 require
在分別發(fā)出最后的 E_WARNING 或 E_ERROR
之前，都會(huì )發(fā)出額外一條 E_WARNING。
如果定義了路徑——不管是絕對路徑（在 Windows
下以盤(pán)符或者 \ 開(kāi)頭，在 Unix/Linux
下以 / 開(kāi)頭）還是當前目錄的相對路徑（以
. 或者 .. 開(kāi)頭）——include_path 都會(huì )被完全忽略。例如一個(gè)文件以
../ 開(kāi)頭，則解析器會(huì )在當前目錄的父目錄下尋找該文件。
有關(guān) PHP 怎樣處理包含文件和包含路徑的更多信息參見(jiàn) include_path 部分的文檔。
當一個(gè)文件被包含時(shí)，其中所包含的代碼繼承了 include 所在行的變量范圍。從該處開(kāi)始，調用文件在該行處可用的任何變量在被調用的文件中也都可用。不過(guò)所有在包含文件中定義的函數和類(lèi)都具有全局作用域。
示例 #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 出現于調用文件中的一個(gè)函數里，則被調用的文件中所包含的所有代碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變量范圍。此規則的一個(gè)例外是魔術(shù)常量，它們是在發(fā)生包含之前就已被解析器處理的。
示例 #2 函數中的包含
<?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
?>
當一個(gè)文件被包含時(shí)，語(yǔ)法解析器在目標文件的開(kāi)頭脫離 PHP 模式并進(jìn)入 HTML 模式，到文件結尾處恢復。由于此原因，目標文件中需要作為 PHP 代碼執行的任何代碼都必須被包括在有效的 PHP 起始和結束標記之中。
如果“URL include wrappers”在 PHP 中被激活，可以用 URL（通過(guò) HTTP 或者其它支持的封裝協(xié)議——見(jiàn)支持的協(xié)議和封裝協(xié)議）而不是本地文件來(lái)指定要被包含的文件。如果目標服務(wù)器將目標文件作為 PHP 代碼解釋?zhuān)瑒t可以用適用于 HTTP GET 的 URL 請求字符串來(lái)向被包括的文件傳遞變量。嚴格的說(shuō)這和包含一個(gè)文件并繼承父文件的變量空間并不是一回事；該腳本文件實(shí)際上已經(jīng)在遠程服務(wù)器上運行了，而本地腳本則包括了其結果。
示例 #3 通過(guò) HTTP 進(jìn)行的 include
<?php
/* 這個(gè)示例假定 www.example.com 配置為解析 .php 文件而不解析 .txt 文件。 *
* 此外 “Works” 意味著(zhù) $foo 和 $bar 變量在包含的文件中是可用的。 */
// 無(wú)法執行； file.txt 沒(méi)有被 www.example.com 當作 PHP 處理。
include 'http://www.example.com/file.txt?foo=1&bar=2';
// 無(wú)法執行；在本地文件系統中查找名為 “file.php?foo=1&bar=2” 的文件。
include 'file.php?foo=1&bar=2';
// 正常。
include 'http://www.example.com/file.php?foo=1&bar=2';
?>
遠程文件可能會(huì )經(jīng)遠程服務(wù)器處理（根據文件后綴以及遠程服務(wù)器是否在運行 PHP 而定），但必須產(chǎn)生出一個(gè)合法的 PHP 腳本，因為其將被本地服務(wù)器處理。如果來(lái)自遠程服務(wù)器的文件應該在遠端運行而只輸出結果，那用 readfile() 函數更好。另外還要格外小心以確保遠程的腳本產(chǎn)生出合法并且是所需的代碼。
相關(guān)信息參見(jiàn)使用遠程文件，fopen() 和 file()。
處理返回值：在失敗時(shí) include 返回 FALSE
并且發(fā)出警告。成功的包含則返回
1，除非在包含文件中另外給出了返回值?？梢栽诒话ǖ奈募惺褂?return
語(yǔ)句來(lái)終止該文件中程序的執行并返回調用它的腳本。同樣也可以從被包含的文件中返回值?？梢韵衿胀ê瘮狄粯荧@得
include 調用的返回值。不過(guò)這在包含遠程文件時(shí)卻不行，除非遠程文件的輸出具有合法的 PHP
開(kāi)始和結束標記（如同任何本地文件一樣）?？梢栽跇擞泝榷x所需的變量，該變量在文件被包含的位置之后就可用了。
因為 include 是一個(gè)特殊的語(yǔ)言結構，其參數不需要括號。在比較其返回值時(shí)要注意。
示例 #4 比較 include 的返回值
<?php
// 不能運行，執行 include(('vars.php') == TRUE) 就等于執行 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 是因為 include
成功運行了。注意以上例子中的區別。第一個(gè)在被包含的文件中用了
return 而另一個(gè)沒(méi)有。如果文件不能被包含，則返回
false 并發(fā)出一個(gè) E_WARNING 警告。
如果在包含文件中定義了函數，無(wú)論是在 return 之前還是之后，都可以獨立在主文件（main）中使用。如果文件被包含兩次，由于函數重復定義，PHP 會(huì ) 發(fā)出致命錯誤（fatal error）。推薦使用 include_once 而不是檢查文件是否已包含并在包含文件中有條件返回。
另一個(gè)將 PHP 文件“包含”到一個(gè)變量中的方法是用輸出控制函數結合 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 配置選項。
注意: 因為是一個(gè)語(yǔ)言構造器而不是一個(gè)函數，不能被 可變函數 調用。
參見(jiàn) require、require_once、include_once、 get_included_files()、readfile()、virtual()、 include_path。