用 Xdebug 修正 PHP 應用程式中的錯誤

雖然您可以使用 PHP 為系統管理和傳統資料處理之類的任務建立命令列指令碼，但是程式語言對 Web 應用程式的效能有主要影響。在使用過程中，每個 PHP 應用程式都駐留在伺服器上，並且將通過代理（例如 Apache）呼叫 PHP 應用程式處理到來的請求。對於每個請求，典型的 PHP Web 應用程式在簡短執行後將得到一個 Web 頁面或 XML 資料結構。

假定經過簡單的執行後，一個分層構造的 Web 應用程式 —— 包括客戶機、網路、HTTP 伺服器、應用程式程式碼和底層資料庫 —— 將會很難隔離 PHP 程式碼中的錯誤。即使假定除了 PHP 程式碼以外所有層都可以正常執行，跟蹤 PHP 程式碼中的錯誤也會非常難，尤其是在應用程式利用較多的類時更是如此。

PHP 語句 echo 和函式 var_dump()、debug_zval_dump() 和 print_r() 都是常見且流行的除錯輔助工具，可以幫助解決多種問題。但是，這些語句 —— 甚至更健壯的工具，例如 PEAR Log package —— 都是取證工具，必須在上下文環境之外先進行推測分析才能生成證據。

在某種程度上，通過推論進行除錯是一種蠻幹的做法。收集並篩選資料，嘗試推論出發生的問題。如果缺少重要資訊，則必須重新測試程式碼、重複執行步驟，然後重新開始研究。一種更加高效的方法是在程式執行時探測應用程式。您可以對請求引數分類，篩選過程呼叫堆疊，並查詢任何所需的變數或物件。您可以暫時中斷應用程式並且可以在變數更改值時收到警報。在某些情況下，您可以通過互動式詢問 “如果……會怎樣？” 問題來實際影響變數。

稱為偵錯程式的特殊應用程式支援這種 “實時的” 或互動式的檢查。偵錯程式可能啟動並連線到程序上以便控制程序並監測其記憶體。或者，在使用解釋語言的情況下，偵錯程式可以直接解釋程式碼。典型的現代圖形化偵錯程式可以索引並瀏覽程式碼，以符合人類閱讀習慣的形式輕鬆地顯示覆雜的資料結構，並同時顯示程式狀態，如呼叫堆疊、中間輸出和所有變數的值。例如，偵錯程式通常都會把類的屬性和方法分類並進行描述。

在本文和下一篇文章中，我將介紹的工具一定能夠簡化 PHP 除錯。下一次，我將主要介紹互動式除錯和 Zend Debugger —— 一個特別針對 PHP 的健壯偵錯程式 —— 並探究它提供的許多功能。（Zend Debugger 是一款商業產品，是 Zend PHP 整合開發環境（IDE）的一部分）。我還將介紹一款開源 PHP 偵錯程式，以免您只願把錢花在啤酒上，而不是花在程式碼上。但是，本文將主要介紹如何更好地取證。

類似《犯罪現場調查》，只是更令人討厭

程式碼出錯、未能生成某個所需結果或者徹底崩潰時，您需要回答四個 w 問題：where、what、why 和 when：

“where” 是應用程式最後一次正常執行時所在的檔案和行號。
“what” 是犯錯的程式碼 —— 比如說，嫌疑犯。
“why” 是錯誤的本質。可能它是一個邏輯錯誤和/或與作業系統進行互動所導致的錯誤，或兩者兼具。
而 “when” 是出現錯誤時的上下文。在程式終止前發生了什麼情況？像在所有犯罪行為中一樣，如果您可以收集到足夠的線索，那麼線索就可以幫助您找到犯人。

一種取證工具 Xdebug（上一篇文章中使用的工具，用於分析 PHP 應用程式效能），如名稱所示，將提供幾個說明程式狀態的功能，並且是應當新增到指令系統中的價值頗高的研究工具（請參閱參考資料）。安裝後，Xdebug 將阻止無限次遞迴（表面上是這樣）、修正關於堆疊跟蹤和函式跟蹤的錯誤訊息以及監視記憶體分配，並提供其他功能。Xdebug 還包括一組函式，您可以將這組函式新增到程式碼中以進行執行時錯誤診斷。

例如，下面的程式碼將使用一些 xdebug_...() 步驟測試 callee() 函式，以便輸出呼叫程式的具體位置，包括檔名、行號和呼叫函式的名稱。

清單 1. 測試 callee() 函式的步驟

<?php
    function callee( $a ) {
        echo sprintf("callee() called @ %s: %s from %s",
            xdebug_call_file(),
            xdebug_call_line(),
            xdebug_call_function()
        );
    }

    $result = callee( "arg" );
?>

這段程式碼將生成：

callee() called @ /var/www/catalog/xd.php: 10 from {main}

回頁首

構建和安裝 Xdebug

Xdebug 可以很輕鬆地從 UNIX® 類作業系統（包括 Mac OS X）中的原始碼構建。如果是在 Microsoft® Windows® 上使用 PHP，則可以從 Xdebug Web 站點下載最新 PHP 版本的二進位制 Xdebug 模組（請參閱參考資料）。

讓我們來構建和安裝適用於 Debian “Sarge” Linux® 和 PHP V4.3.10-19 的 Xdebug。在撰寫本文時，Xdebug 的最新版本是 V2.0.0RC4，釋出於 2007 年 5 月 17 日。要繼續本文，必須擁有 phpize 和 php-config 實用程式，並且必須能夠編輯系統的 php.ini 配置檔案（如果沒有實用程式，請訪問 PHP.net 以獲得如何從頭構建 PHP 的原始碼和說明）。請執行以下步驟：

下載 Xdebug tarball（一個用 gzip 壓縮的 .tar 歸檔檔案）。wget 命令可以幫助您輕鬆地完成此操作：
```
 $ wget http://www.xdebug.org/files/xdebug-2.0.0RC4.tgz
```

解壓縮該 tarball 並切換到原始碼目錄：

$ tar xzf xdebug-2.0.0RC4.tgz
$ cd xdebug-2.0.0RC4

執行 phpize 以準備適用於您的 PHP 版本的 Xdebug 程式碼：
```
$ phpize
Configuring for:
PHP Api Version:         20020918
Zend Module Api No:      20020429
Zend Extension Api No:   20021010
```
phpize 的輸出是一個指令碼 —— 通常名為配置 —— 用於調整其餘的構建過程。

執行配置指令碼：

$ ./configure
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables... 
checking for suffix of object files... o
...
checking whether stripping libraries is possible... yes
appending configuration tag "F77" to libtool
configure: creating ./config.status
config.status: creating config.h

通過執行 make 構建 Xdebug 擴充套件：

$ make
/bin/sh /home/strike/tmp/xdebug-2.0.0RC4/libtool
--mode=compile gcc  -I.
-I/home/strike/tmp/xdebug-2.0.0RC4 -DPHP_ATOM_INC
-I/home/strike/tmp/xdebug-2.0.0RC4/include
-I/home/strike/tmp/xdebug-2.0.0RC4/main
-I/home/strike/tmp/xdebug-2.0.0RC4
-I/usr/include/php4 -I/usr/include/php4/main
-I/usr/include/php4/Zend -I/usr/include/php4/TSRM 
-DHAVE_CONFIG_H  -g -O0 -c
/home/strike/tmp/xdebug-2.0.0RC4/xdebug.c -o
xdebug.lo mkdir .libs
...

Build complete.
(It is safe to ignore warnings about tempnam and tmpnam).

使用 make 將生成 Xdebug 擴充套件 xdebug.so。

安裝該擴充套件：
```
$ sudo make install
Installing shared extensions:     /usr/lib/php4/20020429/
```
繼續之前，使用滑鼠選擇並複製上一條命令顯示的目錄。該路徑對於最後一步配置擴充套件至關重要。
在您喜歡的文字編輯器中開啟 php.ini 檔案，然後新增以下程式碼：
```
zend_extension = /usr/lib/php4/20020429/xdebug.so
xdebug.profiler_enable = Off
xdebug.default_enable = On
```
第一行將裝入 Xdebug 擴充套件；第二行將禁用 Xdebug 的分析器功能（只是為了簡單起見），而第三行將啟用擴充套件的除錯功能。

要檢驗 Xdebug 擴充套件是否已經安裝並啟用，請重新啟動 Web 伺服器，然後用程式碼 <?php phpinfo(); ?> 建立簡單的一行 PHP 應用程式。如果將瀏覽器指向檔案 —— 如 http://localhost/phpinfo.php —— 並向下滾動，您應當會看到類似圖 1 所示的內容。

圖 1. 檢驗 Xdebug 擴充套件是否已經安裝並執行

注：如果您在 phpinfo() 的輸出中沒有看到 Xdebug 部分，則 Xdebug 裝入失敗。Apache 錯誤日誌會列出原因。常見錯誤包括zend_extension 的路徑錯誤或者與其他擴充套件發生衝突。例如，如果需要使用 XCache 和 Xdebug，一定要先裝入 XCache。但是，由於 Xdebug 適於在開發時使用並假定 xdebug.so 的路徑正確，因此需要禁用其他擴充套件並重試。然後您可以重新啟用擴充套件以執行其他測試，如快取的效果。Xdebug 站點還有其他一些故障檢修技巧。

回頁首

配置 Xdebug

指令（圖 1 中大表的最左側一列）是一些可以設定的引數，用於改變 Xdebug 擴充套件的行為。可在 php.ini 檔案中設定所有指令。一些指令用於配置除錯工具；其他指令用於調整分析器的操作。忽略後者，讓我們用一些合理設定來配置 Xdebug 以幫助除錯 PHP 程式碼。

限制遞迴

如果應用程式使用遞迴 —— 例如，計算斐波納契數列 —— 並且終端環境不正確，應用程式會執行很長一段時間後才用盡記憶體或超時。您可以設定 xdebug.max_nesting_level 引數來限定遞迴深度。例如，xdebug.max_nesting_level = 50 將把遞迴深度限定為 50 次巢狀呼叫，然後將強制終止應用程式。下面演示一下，在啟用 Xdebug 的狀態下執行下列程式碼：

清單 2. 限制遞迴

<?php
    function deep_end( ) {
        deep_end();
    }
    
    deep_end();
?>

函式 deep_end() 將逐行進行到最底部。Xdebug 將在 49 次函式呼叫後介入並得到圖 2（順便說一句，main() 的初始呼叫用於啟動程式計數作為第 1 次呼叫）。

圖 2. 如果呼叫堆疊超出限制，Xdebug 將終止執行（如果想要顯示如下資訊，需要配置php.ini中的error_reporting和display_errors引數）

如果應用程式大量使用遞迴隔離並解決較大的問題，則需要把深度相應地設定得 “更低”。否則，將 xdebug.max_nesting_level 設為較小的值，這樣可以更快速地捕捉失控的函式呼叫序列。

回答四個 w 問題

出錯時，您需要回答四個 w 問題。Xdebug 可以立即提供所有這些資訊。下面是一些有益的初始設定；您可以隨時調整這些設定。

清單 3. 錯誤

xdebug.dump_once = On
xdebug.dump_globals = On
xdebug.dump_undefined = On
xdebug.dump.SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_USER_AGENT
xdebug.dump.REQUEST=*

xdebug.show_exception_trace = On
xdebug.show_local_vars = 1
xdebug.var_display_max_depth = 6

xdebug.dump_once、xdebug.dump_globals、xdebug.dump_undefined 和 xdebug.dump_SUPERGLOBAL 設定（其中 SUPERGLOBAL 可以是COOKIE、FILES、GET、POST、REQUEST、SERVER 或 SESSION）用於控制哪些 PHP 超全域性變數將被包含在所有診斷結果中。

將 xdebug.dump_globals 設為 On 以轉儲名為 xdebug.dump_SUPERGLOBAL 設定中的超全域性變數。例如，xdebug.dump_SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_USER_AGENT 將列印 PHP 超全域性變數 $_SERVER['REQUEST_METHOD']、$_SERVER['REQUEST_URI'] 和$_SERVER['HTTP_USER_AGENT']。如果需要列印超全域性變數陣列中的所有值，請使用星號 (*)，例如 xdebug.dump_REQUEST=*。如果進一步將xdebug.dump_undefined 設為 On 並且不設定指定的超全域性變數，則仍用值 undefined 列印變數。

即使捕捉到異常，程式碼行 xdebug.show_exception_trace = On 仍將強制執行異常跟蹤。程式碼行 xdebug.show_local_vars = 1 將列印每個函式呼叫的最外圍中的所有區域性變數，包括尚未初始化的變數。而 xdebug.var_display_max_depth = 6 表示轉儲複雜變數的深度。

整合

清單 4 顯示了 php.ini 檔案的 Xdebug 的所有相關設定。

清單 4. php.ini 檔案的設定

zend_extension = /usr/lib/php4/20020429/xdebug.so
xdebug.default_enable = On
xdebug.show_exception_trace = On
xdebug.show_local_vars = 1
xdebug.max_nesting_level = 50
xdebug.var_display_max_depth = 6

xdebug.dump_once = On
xdebug.dump_globals = On
xdebug.dump_undefined = On
xdebug.dump.REQUEST = *
xdebug.dump.SERVER = REQUEST_METHOD,REQUEST_URI,HTTP_USER_AGENT

將這些設定（或類似的內容）儲存到 php.ini 檔案中，然後重新啟動 Web 伺服器。

回頁首

解釋轉儲報告

以下示例顯示了出錯時發生的情況。把您的 “有待改進” 的程式碼修改為類似清單 5 所示的程式碼。

清單 5. 修改錯誤程式碼

<?php
    function deep_end( $count ) {
        // add one to the frame count
        $count += 1;

        if ( $count < 48 ) {
                deep_end( $count );
        }
        else {
                trigger_error( "going off the deep end!" );
        }
    }

    // main() is called to start the program, 
    // so the call stack begins with one frame
    deep_end( 1 );
?>

如果執行這段新程式碼，您應當會看到大量資訊，如下所示：

圖 3. 出錯時超全域性變數、堆疊和區域性變數的轉儲

傳遞給 trigger_error 的訊息文字顯示在頂部。底部是受請求的 $_SERVER 元素列表和已經定義的 $_REQUEST 元素列表。最底部是 #48 範圍中的變數列表，這是根據清單對 deep_end() 進行的呼叫。在呼叫中，$count 是整數 48。當此 Xdebug 配置就緒後，您現在有更多的線索可以跟蹤犯罪者。

下面是另外一個技巧：Xdebug 提供了一個增強型 var_dump() 函式，它對於 PHP 陣列和類尤為有幫助。例如，清單 6 顯示了簡單的（PHP V4）類和例項。

清單 6. PHP V4 類和例項

<?php
    class Person {
        var $name;
        var $surname;
        var $age;
        var $children = array();

        function Person( $name, $surname, $age, $children = null) {
            $this->name = $name;
            $this->surname = $surname;
            $this->age = $age;
            foreach ( $children as $child ) {
                $this->children[] = $child;
            }
        }
    }   

    $boy = new Person( 'Joe', 'Smith', 4 );
    $girl = new Person( 'Jane', 'Smith', 6 );
    $mom = new Person( 'Mary', 'Smith', 34, array( $boy, $girl ) );

    var_dump( $boy, $mom );
?>

清單 7 顯示了 var_dump() 的輸出。

清單 7. `var_dump()` 輸出

object(person)
  var 'name' => string 'Joe' (length=3)
  var 'surname' => string 'Smith' (length=5)
  var 'age' => int 4
  var 'children' => 
    array
      empty
      
object(person)
  var 'name' => string 'Mary' (length=4)
  var 'surname' => string 'Smith' (length=5)
  var 'age' => int 34
  var 'children' => 
    array
      0 => 
        object(person)
          var 'name' => string 'Joe' (length=3)
          var 'surname' => string 'Smith' (length=5)
          var 'age' => int 4
          var 'children' => 
            array
              empty
      1 => 
        object(person)
          var 'name' => string 'Jane' (length=4)
          var 'surname' => string 'Smith' (length=5)
          var 'age' => int 6
          var 'children' => 
            array
              empty

如果結合使用 Xdebug 與 PHP V5 類，轉儲包括 public、private 和 protected 之類的屬性。

回頁首

跟蹤程式碼

解決錯誤 —— 如解開神祕謀殺之謎 —— 通常要求構造詳細的時間線。例如，記憶體洩漏通常不會把自身表明為一個錯誤計算。相反，操作將正常進行，直至記憶體用盡，然後應用程式突然終止。如果記憶體洩漏由於某些請求而惡化，可能會不斷出現錯誤並且難以預測。在記憶體使用量與時間之間建立對映的時間線將揭示洩漏的嚴重程度。一條精細的時間線 —— 比如，從函式到函式 —— 將進一步指出洩漏源。

Xdebug 可以提供一條詳細的時間線進行執行跟蹤。當跟蹤被啟用後，Xdebug 將記錄所有函式呼叫，包括每個函式的引數和返回值。您可以將每個日誌或跟蹤的格式設為符合人類閱讀習慣或者機器可讀的格式。您最好使用前者，雖然您可能編寫獨立而特定的應用程式來分析後者。

同轉儲一樣，Xdebug 有若干個 php.ini 選項用於自定義跟蹤內容。例如，下面一批設定將生成最詳細的輸出。

清單 8. 跟蹤自定義

xdebug.trace_format = 0
xdebug.auto_trace = On
xdebug.trace_output_dir = /tmp/traces
xdebug.trace_output_name = trace.%c.%p

xdebug.collect_params = 4
xdebug.collect_includes = On
xdebug.collect_return = On
xdebug.show_mem_delta = On

設定 xdebug.auto_trace = 1 將在執行所有 PHP 指令碼之前先啟用自動跟蹤。另外，您可以通過程式碼設定 xdebug.auto_trace = 0，並分別使用 xdebug_start_trace() 和 xdebug_stop_trace() 函式啟用和禁用跟蹤。但是，如果 xdebug.auto_trace 為 1，則可以在包括配置好的auto_prepend_file 之前先啟動跟蹤。

選項 xdebug.trace_ouput_dir 和 xdebug.trace_output_name 用於控制儲存跟蹤輸出的位置。在這裡，所有檔案都被儲存到 /tmp/traces 中，並且每個跟蹤檔案都以 trace 為開頭，後接 PHP 指令碼的名稱（%s）以及程序 ID（%p）。所有 Xdebug 跟蹤檔案都以 .xt 字尾結尾。

預設情況下，Xdebug 將顯示時間、記憶體使用量、函式名和函式呼叫深度欄位。如果將 xdebug.trace_format 設為 0，則輸出將符合人類閱讀習慣（將引數設為 1 則為機器可讀格式）。此外，如果指定 xdebug.show_mem_delta = 1，則可以檢視記憶體使用量是在增加還是在減少，而如果指定 xdebug.collect_params = 4，則可以檢視傳入引數的型別和值。要監視每個函式返回的值，請設定 xdebug.collect_return = 1。

接下來看另外一個示例。建立 /tmp/traces 目錄，然後用 mkdir /tmp/traces; chmod a+rwx /tmp/traces 將其模式更改為能夠被任何使用者閱讀的檔案（world-readable）和能夠被任何使用者寫入的檔案（world-writable）（如果您不願共享 traces 目錄，請確保至少 Web 伺服器使用者 —— 通常為 www 或任何人 —— 可以將資料寫入該目錄）。將以上跟蹤設定新增到 php.ini 檔案中，重新啟動 Web 伺服器，然後把瀏覽器再次指向phpinfo() 應用程式。整個跟蹤應當類似清單 9 所示：

清單 9. 整個跟蹤

TRACE START [2007-06-06 14:04:55]
    0.0003       9440    +9440   -> {main}() /var/www/catalog/t/info.php:0
    0.0005       9440       +0     -> phpinfo() /var/www/catalog/t/info.php:1
                                   >=-> TRUE
                                 >=-> 1
    0.2351       9208
TRACE END   [2007-06-06 14:04:55]

在這裡，main() 將呼叫 phpinfo()，後者將返回 TRUE。當 main() 退出時，它將返回 1。接下來，將瀏覽器指向 “最複雜的內容” 或系統中的其他某個 PHP 應用程式以生成更詳細的跟蹤。

清單 10 顯示了在計算第四個斐波納契數列時上一篇文章中的 PHP Fibonacci 生成器的跟蹤：

清單 10. PHP Fibonacci 生成器跟蹤

TRACE START [2007-06-06 14:17:17]
    0.0004      16432   +16432   -> {main}() /var/www/catalog/t/fibonacci.php:0
    0.0006      16696     +264     -> fib('4') /var/www/catalog/t/fibonacci.php:35
    0.0007      16696       +0       -> fib(3) /var/www/catalog/t/fibonacci.php:7
    0.0007      16736      +40         -> fib(2) /var/www/catalog/t/fibonacci.php:7
    0.0007      16848     +112           -> fib(1) /var/www/catalog/t/fibonacci.php:7
                                         >=> 1
    0.0008      16904      +56           -> fib(0) /var/www/catalog/t/fibonacci.php:7
                                         >=> 0
                                       >=> 1
    0.0009      16904       +0         -> fib(1) /var/www/catalog/t/fibonacci.php:7
                                       >=> 1
                                     >=> 2
    0.0009      16904       +0       -> fib(2) /var/www/catalog/t/fibonacci.php:7
    0.0009      16904       +0         -> fib(1) /var/www/catalog/t/fibonacci.php:7
                                       >=> 1
    0.0010      16904       +0         -> fib(0) /var/www/catalog/t/fibonacci.php:7
                                       >=> 0
                                     >=> 1
                                   >=> 3
                                 >=> 1
    0.0011      12528
TRACE END   [2007-06-06 14:17:17]

第一列顯示時間，第二列是累計的記憶體使用量，第三列是增加的記憶體使用量，而第四列顯示函式呼叫，包括引數。

標有 >=> 的行顯示每個函式的返回值（查詢相應的縮排 -> 將呼叫與其返回值匹配起來）。此外，最後的 >=> 1 是 main() 的返回值。

如果使用 vim，Xdebug 的創造者 Derick Rethans 提供了專門針對 Xdebug 跟蹤的一組語法加亮提示。提示包含在 Xdebug 原始碼包內的 xt.vim 檔案中。對於最近的 Linux 發行版，只需將 xt.vim 複製到 $VIMRUNTIME/syntax/xt.vim 中，然後執行 vim tracefile.xt。圖 4 顯示了 vim 中加亮的 Fibonacci 跟蹤。

圖 4. Xdebug 跟蹤的 vim 語法檔案將使您可以輕鬆地進行分析

回頁首

結束語

跟蹤 PHP 程式碼中的錯誤可能是一項挑戰。但是如果您有開發系統並且可以安裝 Xdebug，那麼更正這些錯誤就會變得輕鬆得多。Xdebug 可以顯示堆疊跟蹤，轉儲甚為複雜的變數，隨時間跟蹤記憶體使用量，並允許您在出錯或崩潰時（不是如果，而是發生時）進行有效的事後分析。