include
(PHP 4, PHP 5, PHP 7, PHP 8)
include 表達式包含並執行指定檔案。
以下文件也適用於 require。
被包含檔案先按參數給出的路徑尋找，如果沒有給出目錄（只有檔名）時則按照
include_path 指定的目錄尋找。如果在
include_path 下沒找到該檔案則
include 最後才在呼叫指令碼檔案所在的目錄和目前工作目錄下尋找。如果最後仍未找到檔案則
include 結構會發出一條 E_WARNING ；這一點和
require 不同，後者會發出一個 E_ERROR 。
注意如果檔案無法訪問， include 和 require
在分別發出最後的 E_WARNING 或 E_ERROR
之前，都會發出額外一條 E_WARNING。
如果定義了路徑——不管是絕對路徑（在 Windows
下以碟符或者 \ 開頭，在 Unix/Linux
下以 / 開頭）還是目前目錄的相對路徑（以
. 或者 .. 開頭）——include_path 都會被完全忽略。例如一個檔案以
../ 開頭，則解析器會在目前目錄的父目錄下尋找該檔案。
有關 PHP 怎樣處理包含檔案和包含路徑的更多資訊參見 include_path 部分的文件。
當一個檔案被包含時，其中所包含的程式碼繼承了 include 所在行的變數範圍。從該處開始，呼叫檔案在該行處可用的任何變數在被呼叫的檔案中也都可用。不過所有在包含檔案中定義的函式和類都具有全域性作用域。
示例 #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 出現于呼叫檔案中的一個函式里，則被呼叫的檔案中所包含的所有程式碼將表現得如同它們是在該函式內部定義的一樣。所以它將遵循該函式的變數範圍。此規則的一個例外是魔術常量，它們是在發生包含之前就已被解析器處理的。
示例 #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
?>
當一個檔案被包含時，語法解析器在目標檔案的開頭脫離 PHP 模式並進入 HTML 模式，到檔案結尾處恢復。由於此原因，目標檔案中需要作為 PHP 程式碼執行的任何程式碼都必須被包括在有效的 PHP 起始和結束標記之中。
如果「URL include wrappers」在 PHP 中被啟用，可以用 URL（通過 HTTP 或者其它支援的封裝協議——見支援的協議和封裝協議）而不是本地檔案來指定要被包含的檔案。如果目標伺服器將目標檔案作為 PHP 程式碼解釋，則可以用適用於 HTTP GET 的 URL 請求字串來向被包括的檔案傳遞變數。嚴格的說這和包含一個檔案並繼承父檔案的變數空間並不是一回事；該指令碼檔案實際上已經在遠端伺服器上執行了，而本地指令碼則包括了其結果。
示例 #3 通過 HTTP 進行的 include
<?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';
?>
安全警告
遠端檔案可能會經遠端伺服器處理（根據檔案後綴以及遠端伺服器是否在執行 PHP 而定），但必須產生出一個合法的 PHP 指令碼，因為其將被本地伺服器處理。如果來自遠端伺服器的檔案應該在遠端執行而只輸出結果，那用 readfile() 函式更好。另外還要格外小心以確保遠端的指令碼產生出合法並且是所需的程式碼。
相關資訊參見使用遠端檔案，fopen() 和 file()。
處理返回值：在失敗時 include 返回 FALSE
並且發出警告。成功的包含則返回
1，除非在包含檔案中另外給出了返回值。可以在被包括的檔案中使用 return
語句來終止該檔案中程式的執行並返回呼叫它的指令碼。同樣也可以從被包含的檔案中返回值。可以像普通函式一樣獲得
include 呼叫的返回值。不過這在包含遠端檔案時卻不行，除非遠端檔案的輸出具有合法的 PHP
開始和結束標記（如同任何本地檔案一樣）。可以在標記內定義所需的變數，該變數在檔案被包含的位置之後就可用了。
因為 include 是一個特殊的語言結構，其參數不需要括號。在比較其返回值時要注意。
示例 #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 語句
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
成功執行了。注意以上例子中的區別。第一個在被包含的檔案中用了
return 而另一個沒有。如果檔案不能被包含，則返回
false 併發出一個 E_WARNING 警告。
如果在包含檔案中定義了函式，無論是在 return 之前還是之後，都可以獨立在主檔案（main）中使用。如果檔案被包含兩次，由於函式重複定義，PHP 會 發出致命錯誤（fatal error）。推薦使用 include_once 而不是檢查檔案是否已包含並在包含檔案中有條件返回。
另一個將 PHP 檔案「包含」到一個變數中的方法是用輸出控制函式結合 include 來捕獲其輸出，例如：
示例 #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 和 auto_append_file 配置選項。
參見 require、require_once、include_once、 get_included_files()、readfile()、virtual()、 include_path。