include

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

include 表達式包含并運行指定文件。

以下文檔也適用于 require。

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

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

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

有關 PHP 怎樣處理包含文件和包含路徑的更多信息參見 include_path 部分的文檔。

當一個文件被包含時，其中所包含的代碼繼承了 include 所在行的變量范圍。從該處開始，調用文件在該行處可用的任何變量在被調用的文件中也都可用。不過所有在包含文件中定義的函數(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)于調用文件中的一個函數(shù)里，則被調用的文件中所包含的所有代碼將表現(xiàn)得如同它們是在該函數(shù)內部定義的一樣。所以它將遵循該函數(shù)的變量范圍。此規(guī)則的一個例外是魔術常量，它們是在發(fā)生包含之前就已被解析器處理的。

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


<?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 代碼執(zhí)行的任何代碼都必須被包括在有效的 PHP 起始和結束標記之中。

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

示例 #3 通過 HTTP 進行的 include


<?php

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

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

// 無法執(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';
?>

警告

安全警告

遠程文件可能會經(jīng)遠程服務器處理（根據(jù)文件后綴以及遠程服務器是否在運行 PHP 而定），但必須產(chǎn)生出一個合法的 PHP 腳本，因為其將被本地服務器處理。如果來自遠程服務器的文件應該在遠端運行而只輸出結果，那用 readfile() 函數(shù)更好。另外還要格外小心以確保遠程的腳本產(chǎn)生出合法并且是所需的代碼。

相關信息參見使用遠程文件，fopen() 和 file()。

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

因為 include 是一個特殊的語言結構，其參數(shù)不需要括號。在比較其返回值時要注意。

示例 #4 比較 include 的返回值


<?php
// 不能運行，執(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 語句


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 成功運行了。注意以上例子中的區(qū)別。第一個在被包含的文件中用了 return 而另一個沒有。如果文件不能被包含，則返回 false 并發(fā)出一個 E_WARNING 警告。

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

另一個將 PHP 文件“包含”到一個變量中的方法是用輸出控制函數(shù)結合 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 配置選項。

注意: 因為是一個語言構造器而不是一個函數(shù)，不能被可變函數(shù) 調用。

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