php--require/include/require_once/include_once

require

require 和 include 幾乎完全一樣，除了處理失敗的方式不同之外。 require 在出錯時產生 E_COMPILE_ERROR 層級的錯誤，換句話說將導致指令碼中止而 include 只產生警告（E_WARNING），指令碼會繼續運行。

include

include 語句包含並運行指定檔案。

以下文檔也適用於 require：

被包含檔案先按參數給出的路徑尋找，如果沒有給出目錄（只有檔案名稱）時則按照 include_path 指定的目錄尋找。如果在 include_path 下沒找到該檔案則 include 最後才在呼叫指令碼檔案所在的目錄和當前工作目錄下尋找。如果最後仍未找到檔案則 include 結構會發出一條警告；這一點和 require 不同，後者會發出一個致命錯誤。（關於include_path可參考這篇文章：PHP擴充之選項和配置資訊）

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

當一個檔案被包含時，其中所包含的代碼繼承了 include 所在行的變數範圍。從該處開始，調用檔案在該行處可用的任何變數在被調用的檔案中也都可用。不過所有在包含檔案中定義的函數和類都具有全域範圍。

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 出現於調用檔案中的一個函數裡，則被調用的檔案中所包含的所有代碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變數範圍。此規則的一個例外是魔術常量，它們是在發生包含之前就已被解析器處理的。

Example #2 函數中的包含

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

當一個檔案被包含時，文法解析器在目標檔案的開頭脫離 PHP 模式並進入 HTML 模式，到檔案結尾處恢複。由於此原因，目標檔案中需要作為 PHP 代碼執行的任何代碼都必須被包括在有效 PHP 起始和結束標記之中。

如果“URL fopen wrappers”在 PHP 中被啟用（預設配置），可以用 URL（通過 HTTP 或者其它支援的封裝協議——見支援的協議和封裝協議）而不是本地檔案來指定要被包含的檔案。如果目標伺服器將目標檔案作為 PHP 代碼解釋，則可以用適用於 HTTP GET 的 URL 請求字串來向被包括的檔案傳遞變數。嚴格的說這和包含一個檔案並繼承父檔案的變數空間並不是一回事；該指令檔實際上已經在遠程伺服器上運行了，而本地指令碼則包括了其結果。

WarningWindows 版本的 PHP 在 4.3.0 版之前不支援通過此函數訪問遠程檔案，即使已經啟用 allow_url_fopen.

Example #3 通過 HTTP 進行的 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.?>

安全警告

遠程檔案可能會經遠程伺服器處理（根據檔案尾碼以及遠程伺服器是否在運行 PHP 而定），但必須產生出一個合法的 PHP 指令碼，因為其將被本機伺服器處理。如果來自遠程伺服器的檔案應該在遠端運行而只輸出結果，那用 readfile() 函數更好。另外還要格外小心以確保遠端指令碼產生出合法並且是所需的代碼。

處理傳回值：在失敗時 include 返回 FALSE 並且發出警告。成功的包含則返回 1，除非在包含檔案中另外給出了傳回值。可以在被包括的檔案中使用 return 語句來終止該檔案中程式的執行並返回調用它的指令碼。同樣也可以從被包含的檔案中傳回值。可以像普通函數一樣獲得 include 調用的傳回值。不過這在包含遠程檔案時卻不行，除非遠程檔案的輸出具有合法的 PHP 開始和結束標記（如同任何本地檔案一樣）。可以在標記內定義所需的變數，該變數在檔案被包含的位置之後就可用了。

因為 include 是一個特殊的語言結構，其參數不需要括弧。在比較其傳回值時要注意。

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 語句

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 是因為 include 成功運行了。注意以上例子中的區別。第一個在被包含的檔案中用了 return 而另一個沒有。如果檔案不能被包含，則返回 FALSE 並發出一個E_WARNING 警告。

如果在包含檔案中定義有函數，這些函數不管是在 return 之前還是之後定義的，都可以獨立在主檔案中使用。如果檔案被包含兩次，PHP 5 發出致命錯誤因為函數已經被定義，但是 PHP 4 不會對在 return 之後定義的函數報錯。推薦使用 include_once 而不是檢查檔案是否已包含並在包含檔案中有條件返回。

另一個將 PHP 檔案“包含”到一個變數中的方法是用輸出控制函數結合 include 來捕獲其輸出，例如：

Example #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 配置選項。

Note: 因為是一個語言構造器而不是一個函數，不能被 可變函數 調用。

require_once

(PHP 4, PHP 5)

require_once 語句和 require 語句完全相同，唯一區別是 PHP 會檢查該檔案是否已經被包含過，如果是則不會再次包含

include_once

(PHP 4, PHP 5)

include_once 語句在指令碼執行期間包含並運行指定檔案。此行為和 include 語句類似，唯一區別是如果該檔案中已經被包含過，則不會再次包含。如同此語句名字暗示的那樣，只會包含一次。

include_once 可以用於在指令碼執行期間同一個檔案有可能被包含超過一次的情況下，想確保它只被包含一次以避免函數重定義，變數重新賦值等問題。

Note:

在 PHP 4中，_once 的行為在不區分大小寫字母的作業系統（例如 Windows）中有所不同，例如：

Example #1 include_once 在 PHP 4 運行於不區分大小寫作業系統中

<?phpinclude_once "a.php"; // 這將包含 a.phpinclude_once "A.php"; // 這將再次包含 a.php！（僅 PHP 4）?>

此行為在 PHP 5 中改了，例如在 Windows 中路徑先被規格化，因此 C:\PROGRA~1\A.php 和 C:\Program Files\a.php 的實現一樣，檔案只會被包含一次。

