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 = &#39;green&#39;;
    $fruit = &#39;apple&#39;;
?>
test.php
<?php
    echo "A $color $fruit"; // A
    include &#39;vars.php&#39;;
    echo "A $color $fruit"; // A green apple
?>

如果 include 出現於呼叫檔案中的一個函數裡，則被呼叫的檔案中所包含的所有程式碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變數範圍。此規則的一個例外是魔術常數，它們是在發生包含之前就已被解析器處理的。

Example #2 函數中的包含

<?php
function foo()
{
    global $color;
    include &#39;vars.php&#39;;
    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 apple
echo "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, &#39;Works&#39; here means that the variables *
     * $foo and $bar are available within the included file. */
    // Won&#39;t work; file.txt wasn&#39;t handled by www.example.com as PHP
    include &#39;http://www.example.com/file.txt?foo=1&bar=2&#39;;
    // Won&#39;t work; looks for a file named &#39;file.php?foo=1&bar=2&#39; on the
    // local filesystem.
    include &#39;file.php?foo=1&bar=2&#39;;
    // Works.
    include &#39;http://www.example.com/file.php?foo=1&bar=2&#39;;
    $foo = 1;
    $bar = 2;
    include &#39;file.txt&#39;; // Works.
    include &#39;file.php&#39;; // Works.
?>

Example #3 透過HTTP 進行的 include

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

安全警告

處理（根據檔案後綴以及遠端伺服器是否在執行PHP 而定），但必須產生一個合法的PHP 腳本，因為其將由本機伺服器處理。如果來自遠端伺服器的檔案應該在遠端運作而只輸出結果，那麼用 readfile() 函數比較好。另外也要格外小心以確保遠端的腳本產生合法並且是所需的程式碼。

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

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

Example #4 比较 include 的返回值

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

Example #5 include 和 return 语句

return.php
5e761dc189df02af8b3a77896bf6f89f

noreturn.php
ebe9369892d7384cf276f620b752f65d

testreturns.php
3f955376bfdcb5b15a5de19c4f63fc0f

$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(&#39;somefile.php&#39;);
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 运行于不区分大小写的操作系统中

<?php
include_once "a.php"; // 这将包含 a.php
include_once "A.php"; // 这将再次包含 a.php！（仅 PHP 4）
?>

 

此行为在 PHP 5 中改了，例如在 Windows 中路径先被规格化，因此 C:\PROGRA~1\A.php 和 C:\Program Files\a.php 的实现一样，文件只会被包含一次。