(PHP 4, PHP 5, PHP 7)
include 語句包含并運行指定文件。
以下文檔也適用于 require。
被包含文件先按參數給出的路徑尋找,如果沒有給出目錄(只有文件名)時則按照 include_path 指定的目錄尋找。如果在 include_path 下沒找到該文件則 include 最后才在調用腳本文件所在的目錄和當前工作目錄下尋找。如果最后仍未找到文件則 include 結構會發出一條警告;這一點和 require 不同,后者會發出一個致命錯誤。
如果定義了路徑——不管是絕對路徑(在 Windows 下以盤符或者 \ 開頭,在 Unix/Linux 下以 / 開頭)還是當前目錄的相對路徑(以 . 或者 .. 開頭)——include_path 都會被完全忽略。例如一個文件以 ../ 開頭,則解析器會在當前目錄的父目錄下尋找該文件。
有關 PHP 怎樣處理包含文件和包含路徑的更多信息參見 include_path 部分的文檔。
當一個文件被包含時,其中所包含的代碼繼承了 include 所在行的變量范圍。從該處開始,調用文件在該行處可用的任何變量在被調用的文件中也都可用。不過所有在包含文件中定義的函數和類都具有全局作用域。
** 基本的 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 出現于調用文件中的一個函數里,則被調用的文件中所包含的所有代碼將表現得如同它們是在該函數內部定義的一樣。所以它將遵循該函數的變量范圍。此規則的一個例外是魔術常量,它們是在發生包含之前就已被解析器處理的。
**函數中的包含**
~~~
<?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 或者其它支持的封裝協議——見支持的協議和封裝協議)而不是本地文件來指定要被包含的文件。如果目標服務器將目標文件作為 PHP 代碼解釋,則可以用適用于 HTTP GET 的 URL 請求字符串來向被包括的文件傳遞變量。嚴格的說這和包含一個文件并繼承父文件的變量空間并不是一回事;該腳本文件實際上已經在遠程服務器上運行了,而本地腳本則包括了其結果。
Warning
Windows 版本的 PHP 在 4.3.0 版之前不支持通過此函數訪問遠程文件,即使已經啟用 allow_url_fopen.
**通過 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.
?>
~~~
Warning
安全警告
遠程文件可能會經遠程服務器處理(根據文件后綴以及遠程服務器是否在運行 PHP 而定),但必須產生出一個合法的 PHP 腳本,因為其將被本地服務器處理。如果來自遠程服務器的文件應該在遠端運行而只輸出結果,那用 readfile() 函數更好。另外還要格外小心以確保遠程的腳本產生出合法并且是所需的代碼。
相關信息參見使用遠程文件,fopen() 和 file()。
處理返回值:在失敗時 include 返回 FALSE 并且發出警告。成功的包含則返回 1,除非在包含文件中另外給出了返回值。可以在被包括的文件中使用 return 語句來終止該文件中程序的執行并返回調用它的腳本。同樣也可以從被包含的文件中返回值。可以像普通函數一樣獲得 include 調用的返回值。不過這在包含遠程文件時卻不行,除非遠程文件的輸出具有合法的 PHP 開始和結束標記(如同任何本地文件一樣)。可以在標記內定義所需的變量,該變量在文件被包含的位置之后就可用了。
因為 include 是一個特殊的語言結構,其參數不需要括號。在比較其返回值時要注意。
** 比較 include 的返回值**
~~~
<?php
// won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
if (include('vars.php') == 'OK') {
echo 'OK';
}
// works
if ((include 'vars.php') == 'OK') {
echo 'OK';
}
?>
~~~
** 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 來捕獲其輸出,例如:
**使用輸出緩沖來將 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,require_once,include_once,get_included_files(),readfile(),virtual() 和 include_path。
- 入門指引
- 簡介
- PHP是什么
- PHP能做什么
- 簡明教程
- 學PHP需要什么
- 我的第一個PHP頁面
- 實用的PHP腳步
- PHP是如何處理表單的
- 在新版本的PHP如何實用舊的PHP代碼
- 下一步需要做什么
- PHP語言參考
- PHP基本語法
- PHP標記
- PHP多進程管理-pcntl_fork
- PHP文件上傳易犯錯誤
- PHP從HTML中分離
- PHP的指令分隔符
- PHP序列化serialize
- PHP類常量
- PHP Traits
- 從 HTML 中分離
- 注釋
- PHP數據類型
- PHP支持的類型簡介
- 布爾類型(Boolean)就是易經知識
- 整型(integer)即整數
- 浮點型(float)
- 字符串(string)
- 數組(Array)
- 對象(object)一定要搞
- 資源類型(resource)
- PHP安裝與環境配置
- 安裝前需要考慮的事項
- Unix系統下安裝PHP
- Unix 系統下安裝 Apache 1.3.x
- Unix 系統下安裝 Apache 2.x
- Unix 系統下安裝 Nginx 1.4.x
- Unix 平臺安裝 Lighttpd 1.4
- Sun Solaris 上的 Sun、iPlanet 和 Netscape 服務器
- CGI 命令行設置
- 針對 HP-UX 平臺的安裝提示
- 在 OpenBSD 系統下的安裝PHP
- Debian GNU/Linux 安裝說明
- 在Mac OS X 系統下安裝PHP
- 使用軟件包
- 使用內置的 PHP
- Windows 系統下的安裝
- 云計算平臺上的安裝
- Microsoft Azure
- 在亞馬遜(Amazon EC2)安裝PHP
- PHP語法參考
- 類型
- NULL
- Callback 回調類型
- 本文檔中使用的偽類型與變量
- 類型轉換的判別
- PHP 類型比較表
- 常量和變量
- 語法基礎
- 預定義變量
- 變量范圍
- 可變變量
- 外部變量
- 常量
- 語法
- 魔術常量
- PHP表達式&運算符
- 賦值運算符
- 位運算符
- 比較運算符
- 錯誤控制運算符
- 執行運算符
- 遞增/遞減運算符
- 邏輯運算符
- 字符串運算符
- 數組運算符
- 類型運算符
- 流程控制
- continue
- switch
- declare
- return
- require
- include
- require_once