在 WSL 2 中使用 PHP XDebug

XDebug 在昨日正式發佈 3.0.0。
XDebug 是身為 PHPer 必用的一個套件,可以在程式碼中設定斷點,中斷程式執行並查看程式執行的數據。
但小弟是菜雞工程師,加上 Laravel 的 dd() 實在是太過好用,所以一直都還沒有很深入的去使用過 XDebug(慚愧)。

// Laravel 中超級好用的除錯方法
dd();

那麼要如何在 Windows WSL 中使用 XDebug 呢?

本篇文章會閱讀前可以要先服用另一篇部落格文章,在 Windows 中安裝 WSL 2。由於小弟很習慣 Mac 的套件管理 Homebrew,所以此篇文章會以 Linux 版本的 Homebrew 來安裝 PHP 與 Xdebug

安裝 PHP 與 Xdebug


安裝 PHP。

brew install php

Homebrew 安裝的 PHP,會連 PECL 與 PEAR 都一起安裝好,使用 PECL 安裝 XDebug。

pecl install xdebug

這時候你可能會出現如下面安裝錯誤的問題,詳細可以參考這個 issue

Warning: mkdir(): File exists in System.php on line 294
PHP Warning:  mkdir(): File exists in /home/linuxbrew/.linuxbrew/Cellar/php/8.0.3/share/php/pear/System.php on line 294

Warning: mkdir(): File exists in /home/linuxbrew/.linuxbrew/Cellar/php/8.0.3/share/php/pear/System.php on line 294
ERROR: failed to mkdir /home/linuxbrew/.linuxbrew/Cellar/php/8.0.3/pecl/20200930

錯誤原因是無法使用 mkdir() 創建目錄,使用指令檢查一下路徑。

ll /home/linuxbrew/.linuxbrew/Cellar/php/8.0.3

結果如下。

total 64K
-rw-r--r-- 1 shark shark 3.8K Mar  9 09:42 INSTALL_RECEIPT.json
-rw-r--r-- 1 shark shark 3.2K Mar  3 00:37 LICENSE
-rw-r--r-- 1 shark shark  24K Mar  3 00:37 NEWS
-rw-r--r-- 1 shark shark 5.2K Mar  3 00:37 README.md
drwxr-xr-x 2 shark shark 4.0K Mar  9 09:41 bin
-rw-r--r-- 1 shark shark  676 Mar  9 09:41 homebrew.mxcl.php.plist
drwxr-xr-x 3 shark shark 4.0K Mar  9 09:41 include
drwxr-xr-x 4 shark shark 4.0K Mar  9 09:41 lib
lrwxrwxrwx 1 shark shark   39 Mar  9 09:41 pecl -> /home/linuxbrew/.linuxbrew/lib/php/pecl
drwxr-xr-x 2 shark shark 4.0K Mar  9 09:41 sbin
drwxr-xr-x 4 shark shark 4.0K Mar  9 09:41 share

從結果來看 /home/linuxbrew/.linuxbrew/Cellar/php/8.0.3 底下已經有一個 pecl 的目錄了,但是這個目錄是 symbolic link (軟連結),檢查一下軟連結對應的目錄。

ll /home/linuxbrew/.linuxbrew/lib/php/pecl

結果如下。

ls: cannot access '/home/linuxbrew/.linuxbrew/lib/php/pecl': No such file or directory

原來軟連結對應的目錄並沒有被創建,在軟連結指定路徑新建這個目錄來解決問題吧。

mkdir /home/linuxbrew/.linuxbrew/lib/php/pecl

目錄創建好之後重新使用 pecl 安裝 xdebug。

pecl install xdebug

這時候安裝應該就可以成功了,並且會看到提示訊息已經啟用 xdebug。
此時 php.ini 檔案最上方就會多一行。

可以使用 php --ini 查看 php.ini 的檔案路徑

zend_extension="xdebug.so"

也可以使用 phpinfo() 來查看是否已經裝好 XDebug。

phpinfo();
2021_07_14_19_30_16_60eecac8b673a.jpg
有這一個區塊就代表 XDebug 已經成功安裝

或是使用 php 檢查版本的指令來查看。

php -v

顯示的結果會有 with Xdebug… 的字串。

PHP 8.0.9 (cli) (built: Jul 29 2021 17:21:21) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.9, Copyright (c) Zend Technologies
    with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethans
    with Zend OPcache v8.0.9, Copyright (c), by Zend Technologies

在 VSCode 中使用 XDebug


想要在 VSCode 中使用 XDebug,需要先安裝 PHP Debug 這個 VSCode 套件

2021_07_14_19_30_24_60eecad06b824.jpg
PHPer 必裝套件之一

還需要 php.ini 中加上以下這些設定。

[XDebug]
; 開啟 debug mode
xdebug.mode=debug

; 預設使用的 host 就是 127.0.0.1,所以這邊其實不需要再次設定
xdebug.client_host=127.0.0.1

; 預設使用的 port 就是 9003,所以這邊其實不需要再次設定
; Xdebug 3.0.0 將預設的 port 從 9000 改為 9003
xdebug.client_port=9003

; xdebug.remote_autostart 在 3.0.0 已被移除
; 可以使用 xdebug.start_with_request 或者是 xdebug.start_upon_error
; 設定 yes 可以在接收到請求或是執行 PHP Script 時就觸發 xdebug 並中斷程式執行 
xdebug.start_with_request=yes

更改 php.ini 之後,需要重新載入 php 或是 php-fpm

開啟需要除錯的專案,點擊左方 VSCode 的除錯功能,並建立 launch.json 檔案。

2021_07_14_19_30_33_60eecad95aa52.jpg
要使用 Debug 功能,需要先建立一個 launch.json 檔案

環境選擇 PHP。

2021_07_14_19_30_41_60eecae14bc40.jpg
必須先安裝 PHP Debug 套件,才會有 PHP 這個選項

此時 VSCode 會在專案底下建立一個 .vscode/launch.json

{
    // 使用 IntelliSense 以得知可用的屬性。
    // 暫留以檢視現有屬性的描述。
    // 如需詳細資訊,請瀏覽: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        },
        {
            "name": "Launch Built-in web server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:0"
            ],
            "program": "",
            "cwd": "${workspaceRoot}",
            "port": 9003,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

前置設定好,就可以開始使用 XDebug 的除錯功能,在你想要中斷的地方,設置中斷點,然後開始執行 Debug 功能。

2021_07_14_19_30_50_60eecaea634d1.jpg
在行數數字前面點一下就可以設置中斷點(紅點)

然後重新整理網頁,你會發現程式在中斷點這一行停止執行,並顯示除錯需要的變數相關資訊。

2021_07_14_19_31_00_60eecaf431fda.jpg
左方會顯示一些除錯的相關資訊

參考資料


Upgrading from Xdebug 2 to 3

sharkHead
written by
sharkHead

後端工程師, PHP 基金會每月 5 鎂小額贊助人 稍微擅長 PHP、Python 與 Google Search,偶爾寫寫 TypeScript 對於逗號後面必須加空格有著絕對的堅持