php檔案調用與包含幾個函數include_once() require_once()include()require()

require()
require() 語句包括並運行指定檔案。

require() 語句包括並運行指定檔案。有關包括如何工作的詳細資料見 include() 的文檔。

require() 和 include() 除了怎樣處理失敗之外在各方面都完全一樣。include() 產生一個警告而 require() 則導致一個致命錯誤。換句話說，如果你想在丟失檔案時停止處理頁面，那就別猶豫了，用 require() 吧。include() 就不是這樣，指令碼會繼續運行。同時也要確認設定了合適的include_path。

例子 16-2. 基本的 require() 例子

<?php教程

require 'prepend.php';

require $somefile;

require ('somefile.txt');

?> 
 

更多例子參見 include() 文檔。

注: 在 php 4.0.2 之前適用以下規則：require() 總是會嘗試讀取目標檔案，即使它所在的行根本就不會執行。條件陳述式不會影響 require()。不過如果 require() 所在的行沒有執行，則目標檔案中的代碼也不會執行。同樣，迴圈結構也不影響 require() 的行為。儘管目標檔案中包含的代碼仍然是迴圈的主體，但 require() 本身只會運行一次。

注: 由於這是一個語言結構而非函數，因此它無法被“變數函數”調用。

include()
include() 語句包括並運行指定檔案。

以下文檔也適用於 require()。這兩種結構除了在如何處理失敗之外完全一樣。include() 產生一個警告而 require() 則導致一個致命錯誤。換句話說，如果你想在遇到丟失檔案時停止處理頁面就用 require()。include() 就不是這樣，指令碼會繼續運行。同時也要確認設定了合適的 include_path。

當一個檔案被包括時，其中所包含的代碼繼承了 include 所在行的變數範圍。從該處開始，調用檔案在該行處可用的任何變數在被調用的檔案中也都可用。

例子 16-3. 基本的 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 出現於調用檔案中的一個函數裡，則被調用的檔案中所包含的所有代碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變數範圍。

例子 16-4. 函數中的包括

<?php

function 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 apple
echo "a $color $fruit";  // a green

?> 
 

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

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

警告
windows 版本的 php 在 4.3.0 版之前不支援本函數的遠程檔案訪問，即使 allow_url_fopen 選項已被啟用。
 

例子 16-5. 通過 http 進行的 include()

<?php

/* this example assumes that www.111cn.net 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.

?> 
 

相關資訊參見使用遠程檔案，fopen() 和 file()。

因為 include() 和 require() 是特殊的語言結構，在條件陳述式中使用必須將其放在語句組中（花括弧中）。

例子 16-6. include() 與條件陳述式組

<?php

// this is wrong and will not work as desired.
if ($condition)
   include $file;
else
   include $other;

// this is correct.
if ($condition) {
   include $file;
} else {
   include $other;
}

?> 
 

處理傳回值：可以在被包括的檔案中使用 return() 語句來終止該檔案中程式的執行並返回調用它的指令碼。同樣也可以從被包括的檔案中傳回值。可以像普通函數一樣獲得 include 呼叫的傳回值。

注: 在 php 3 中，除非是在函數中調用否則被包括的檔案中不能出現 return。在此情況下 return() 作用於該函數而不是整個檔案。

例子 16-7. 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() 而另一個沒有。其它幾種把檔案“包括”到變數的方法是用 fopen()，file() 或者 include() 連同輸出控制函數一起使用。

注: 由於這是一個語言結構而非函數，因此它無法被“變數函數”調用。
require_once()
require_once() 語句在指令碼執行期間包括並運行指定檔案。此行為和 require() 語句類似，唯一區別是如果該檔案中的代碼已經被包括了，則不會再次包括。有關此語句怎樣工作參見 require() 的文檔。

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

使用 require_once() 和 include_once() 的例子見最新的 php 來源程式發行包中的 pear 代碼。

注: require_once() 是 php 4.0.1pl2 中新加入的。

 

注: 要注意 require_once() 和 include_once() 在大小寫不敏感的作業系統中（例如 windows）的行為可能不是你所期望的。 例子 16-8. require_once() 在 windows 下不區分大小寫

<?php
require_once("a.php"); // this will include a.php
require_once("a.php"); // this will include a.php again on windows!
?> 

 

 

警告
windows 版本的 php 在 4.3.0 版之前不支援本函數的遠程檔案訪問，即使 allow_url_fopen 選項已被啟用。
 

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

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

使用 require_once() 和 include_once() 的更多例子見最新的 php 來源程式發行包中的 pear 代碼。

注: include_once() 是 php 4.0.1pl2 中新加入的。

 

注: 要注意 include_once() 和 require_once() 在大小寫不敏感的作業系統中（例如 windows）的行為可能不是你所期望的。 例子 16-9. include_once() 在 windows 下不區分大小寫

<?php
include_once("a.php"); // this will include a.php
include_once("a.php"); // this will include a.php again on windows!
?> 
 

 

警告
windows 版本的 php 在 4.3.0 版之前不支援本函數的遠程檔案訪問，即使 allow_url_fopen 選項已被啟用。