Debug PHP với Xdebug: Hướng dẫn từng bước cho PhpStorm & VSCode

Chán việc chèn các câu lệnh var_dump() và dd() khắp mọi nơi? Xdebug biến việc debug PHP từ phỏng đoán thành điều tra chính xác, từng bước. Bạn sẽ thấy chính xác code của mình làm gì, kiểm tra biến tại bất kỳ điểm nào, và theo dõi luồng thực thi—tất cả mà không cần sửa code.

Với tính năng cài Xdebug một chạm của FlyEnv, bạn có thể thiết lập debug chuyên nghiệp trong vài phút thay vì hàng giờ chỉnh sửa tệp cấu hình.

Vì sao Xdebug thay đổi mọi thứ

Debug truyền thống (không có Xdebug)

php

public function calculateTotal($items)
{
    $total = 0;
    foreach ($items as $item) {
        $price = $item->price;
        var_dump($price); // Remove this later
        $total += $price;
    }
    dd($total); // Die and dump
    return $total;
}

Các vấn đề:

Code lộn xộn với các câu lệnh debug
Quên xóa code debug trước khi commit
Khó nhìn thấy các giá trị trung gian
Không có khả năng quan sát luồng thực thi

Debug với Xdebug

php

public function calculateTotal($items)
{
    $total = 0;
    foreach ($items as $item) {
        $price = $item->price; // Set breakpoint here
        $total += $price;
    }
    return $total;
}

Đặt một breakpoint. Xong. Kiểm tra biến, đi từng bước qua các vòng lặp, xem call stack—tất cả ngay trong IDE của bạn.

Cài đặt Xdebug trong FlyEnv

macOS & Linux: Cài đặt một chạm

FlyEnv cung cấp cách nhanh nhất để cài Xdebug—không cần tải xuống thủ công hay săn lùng cấu hình.

Mở module PHP của FlyEnv
Chọn phiên bản PHP của bạn
Nhấp tab "Extensions"
Tìm Xdebug trong danh sách
Nhấp Install

Xdebug được tải xuống và cài đặt tự động:

Bạn sẽ thấy Xdebug được liệt kê là đã cài đặt:

Windows: Cài đặt thủ công

Windows đòi hỏi tải xuống thủ công (do tính tương thích binary của PHP):

Trong module PHP của FlyEnv, nhấp nút "Extension"
Thao tác này mở website PECL và thư mục extension PHP của bạn

Truy cập https://pecl.php.net/package/xdebug
Tải xuống tệp xdebug.dll khớp với phiên bản PHP của bạn (TS/NTS, x64/x86)
Đặt xdebug.dll vào thư mục extension PHP của bạn (đã mở ở bước 2)

Mẹo: Dùng Xdebug Wizard nếu bạn không chắc nên tải DLL nào.

Cấu hình Xdebug

Cấu hình nhanh với các mẫu có sẵn

FlyEnv đi kèm các mẫu Xdebug được cấu hình sẵn—không cần nhớ thuộc lòng các thiết lập.

Trong module PHP, nhấp "Conf" để chỉnh sửa php.ini
Tìm tới phần cấu hình Xdebug
Nhấp nút template/copy để chèn các thiết lập được khuyến nghị

Cấu hình Xdebug được khuyến nghị

Dán đoạn này vào php.ini của bạn (macOS/Linux):

ini

[xdebug]
zend_extension = "xdebug.so"
xdebug.idekey = "PHPSTORM"
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.mode = debug
xdebug.profiler_append = 0
xdebug.profiler_output_name = cachegrind.out.%p
xdebug.start_with_request = yes
xdebug.trigger_value = StartProfileForMe
xdebug.output_dir = /tmp

Với Windows, đổi dòng extension thành:

ini

zend_extension = "xdebug.dll"

Giải thích cấu hình

Thiết lập	Giá trị	Mục đích
`xdebug.mode`	`debug`	Bật debug (không phải profiling)
`xdebug.client_port`	`9003`	Cổng IDE lắng nghe (mặc định của PhpStorm)
`xdebug.idekey`	`PHPSTORM`	Định danh để khớp với IDE
`xdebug.start_with_request`	`yes`	Tự động bắt đầu debug với mọi yêu cầu
`xdebug.client_host`	`localhost`	Nơi IDE đang chạy

Khởi động lại PHP

Sau khi lưu php.ini:

Khởi động lại dịch vụ PHP trong FlyEnv
Tạo một tệp kiểm tra phpinfo.php:
php
```
<?php phpinfo(); ?>
```
Truy cập tệp đó trong trình duyệt
Tìm kiếm "Xdebug"—bạn sẽ thấy thông tin phiên bản

Cấu hình IDE

Thiết lập PhpStorm

Bước 1: Đặt PHP Interpreter

Mở Preferences → PHP
Đặt CLI Interpreter thành phiên bản PHP của FlyEnv

Bước 2: Cấu hình cổng Xdebug

Đi tới Preferences → PHP → Debug
Đặt Debug port thành 9003 (khớp với php.ini)

Bước 3: Đặt IDE Key và Host

Trong cài đặt Debug, đặt:
- IDE key: PHPSTORM (khớp với php.ini)
- Host: localhost

Bước 4: Bắt đầu lắng nghe

Nhấp nút "Start Listening for PHP Debug Connections" (biểu tượng điện thoại) trên thanh công cụ:

Bước 5: Đặt breakpoint và debug

Mở một tệp PHP trong dự án của bạn
Nhấp vào phần lề để đặt breakpoint (xuất hiện chấm đỏ)
Truy cập site của bạn trong trình duyệt
PhpStorm sẽ nhắc bạn chấp nhận kết nối:

Nhấp "Accept"—bây giờ bạn đang ở chế độ debug:

Các bảng điều khiển của trình gỡ lỗi:

Frames: Call stack hiển thị đường dẫn thực thi
Variables: Kiểm tra mọi biến trong phạm vi
Watches: Theo dõi các biểu thức cụ thể
Console: Thực thi mã PHP trong ngữ cảnh hiện tại

Thiết lập VSCode

Bước 1: Cài đặt extension PHP Debug

Mở view Extensions (Ctrl+Shift+X)
Tìm kiếm "PHP Debug"
Cài đặt extension của Felix Becker

Tải lại cửa sổ VSCode sau khi cài đặt

Bước 2: Thêm cấu hình debug

Chuyển sang view Debug (Ctrl+Shift+D)
Nhấp "create a launch.json file"

Chọn "PHP" làm môi trường

Bước 3: Cấu hình launch.json

VSCode tạo tệp .vscode/launch.json. Thêm thuộc tính runtimeExecutable trỏ tới PHP của FlyEnv:

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "runtimeExecutable": "/Users/username/.flyenv/php/8.3.11/bin/php"
        }
    ]
}

Tìm đường dẫn PHP của bạn:

bash

which php
# or
flyenv php path

Bước 4: Bắt đầu debug

Nhấp nút "Start Debugging" màu xanh lá (biểu tượng play)
Đặt breakpoint trong code của bạn
Truy cập site của bạn trong trình duyệt

Bước 5: Các phím điều khiển debug

Khi một breakpoint bị chạm tới:

Debug Console hiển thị giá trị biến và chi tiết thực thi.

Phím tắt:

Phím	Hành động
F5	Tiếp tục / Chạy tới breakpoint kế tiếp
F10	Step Over (thực thi dòng, không đi vào hàm)
F11	Step Into (đi vào lời gọi hàm)
Shift + F11	Step Out (trở về từ hàm hiện tại)

Các kỹ thuật debug thiết yếu

1. Breakpoint có điều kiện

Chỉ dừng khi các điều kiện cụ thể được thỏa mãn:

php

// Right-click breakpoint → More → Condition
$user->id === 123
$total > 1000
!empty($items)

2. Theo dõi biểu thức

Giám sát các biến hoặc biểu thức cụ thể:

$user->email
count($cart->items)
$request->input('search')

3. Đánh giá mã

Thực thi mã PHP trong khi debug:

php

// In PhpStorm Console or VSCode Debug Console
$user->refresh();
DB::table('logs')->where('id', 1)->first();

4. Truy vết stack

Xem cách bạn đi tới dòng hiện tại:

#0 app/Http/Controllers/OrderController.php(45)
#1 vendor/laravel/framework/src/Routing/ControllerDispatcher.php(48)
#2 vendor/laravel/framework/src/Routing/Route.php(262)
...

Nhấp vào bất kỳ frame nào để kiểm tra các biến tại điểm đó của quá trình thực thi.

Khắc phục sự cố

"Xdebug not loading" trong phpinfo()

Nguyên nhân:

Đường dẫn extension sai
Phiên bản không khớp (TS so với NTS)
PHP chưa được khởi động lại sau khi thay đổi cấu hình

Cách sửa:

Xác minh đường dẫn zend_extension chính xác
Kiểm tra log lỗi PHP để tìm lỗi tải
Bảo đảm PHP đã được khởi động lại trong FlyEnv

"Cannot accept external Xdebug connection"

Nguyên nhân: Cổng không khớp hoặc tường lửa

Cách sửa:

Xác minh cổng 9003 ở cả php.ini và IDE
Kiểm tra tường lửa không chặn localhost:9003
Bảo đảm IDE đang lắng nghe trước khi gửi yêu cầu

"Connection refused" hoặc timeout

Nguyên nhân: Xdebug không kết nối được tới IDE

Cách sửa:

ini

; Try these settings in php.ini
xdebug.client_host = 127.0.0.1
xdebug.discover_client_host = 1
xdebug.client_port = 9003

Debug không khởi động

Nguyên nhân: Thiết lập start_with_request

Cách sửa:

xdebug.start_with_request = yes — Debug mọi yêu cầu (chỉ dành cho phát triển)
xdebug.start_with_request = trigger — Chỉ khi được kích hoạt (thêm ?XDEBUG_TRIGGER=1 vào URL)

Breakpoint không bị chạm tới

Danh sách kiểm tra:

[ ] Đã cấu hình path mapping chính xác (PhpStorm)
[ ] Tệp trên server khớp với tệp local
[ ] Breakpoint nằm trên dòng có thể thực thi (không phải dòng trống/chú thích)
[ ] Chế độ Xdebug là debug (không phải profile hay off)

Profiling hiệu năng (Bonus)

Xdebug cũng có thể profile code của bạn để tìm các điểm nghẽn:

ini

xdebug.mode = profile
xdebug.start_with_request = trigger
xdebug.output_dir = /tmp

Kích hoạt profiling bằng cách thêm ?XDEBUG_PROFILE=1 vào bất kỳ URL nào. Phân tích kết quả bằng:

KCachegrind (Linux)
QCachegrind (macOS/Windows)
PhpStorm (profiler tích hợp sẵn)

Câu hỏi thường gặp (FAQ)

H: Xdebug có làm chậm ứng dụng của tôi không?

Đ: Có, từ 10-50% khi đang bật. Chỉ bật nó cho việc phát triển, không bao giờ dùng cho production. Dùng xdebug.mode = off để tắt mà không cần gỡ cài đặt.

H: Tôi có thể dùng Xdebug với Laravel Sail không?

Đ: Có, nhưng khá phức tạp. Với FlyEnv, Xdebug hoạt động native mà không có các phức tạp về mạng Docker.

H: Xdebug 2 và 3 khác nhau thế nào?

Đ: FlyEnv cài Xdebug 3.x vốn có cấu hình đơn giản hóa. Các thiết lập như remote_enable được thay bằng mode = debug.

H: Tôi có thể debug các script CLI không?

Đ: Có. Trong PhpStorm, dùng "Run > Debug" trên script của bạn. Trong VSCode, cấu hình một cấu hình "Launch currently open script".

H: Vì sao dùng cổng 9003 thay vì 9000?

Đ: Xdebug 3 đã đổi cổng mặc định từ 9000 thành 9003 để tránh xung đột với PHP-FPM vốn thường dùng 9000.

H: Tôi có thể debug các yêu cầu AJAX không?

Đ: Có. Xdebug hoạt động với bất kỳ yêu cầu HTTP nào—tải trang, AJAX, lời gọi API. Chỉ cần bảo đảm IDE của bạn đang lắng nghe.

H: Làm thế nào để chỉ debug những yêu cầu cụ thể?

Đ: Đổi thành xdebug.start_with_request = trigger và thêm ?XDEBUG_TRIGGER=1 vào các URL bạn muốn debug.

H: Tôi có thể dùng Xdebug với các bài kiểm thử PHPUnit không?

Đ: Hoàn toàn được. Đặt breakpoint trong các phương thức kiểm thử hay mã nguồn, rồi chạy kiểm thử với debug được bật trong IDE của bạn.

H: Xdebug có hoạt động với PHP 8+ không?

Đ: Có. Xdebug 3.0+ hỗ trợ đầy đủ PHP 8.0, 8.1, 8.2, và 8.3 bao gồm các tính năng mới như named arguments và attributes.

Tóm tắt

Xdebug + FlyEnv mang lại cho bạn khả năng debug PHP chuyên nghiệp:

✅ Cài đặt một chạm trên macOS/Linux
✅ Các mẫu cấu hình sẵn trong FlyEnv
✅ Debug từng bước trong PhpStorm và VSCode
✅ Kiểm tra biến và đánh giá biểu thức
✅ Truy vết call stack cho các ứng dụng phức tạp

Đừng đoán mò code của bạn làm gì nữa. Hãy trực tiếp nhìn thấy nó.

Tải xuống FlyEnv — Có sẵn cho macOS, Windows, và Linux

Các hướng dẫn liên quan:

Chạy Laravel với FlyEnv — Thiết lập riêng cho Laravel
Cô lập phiên bản theo dự án — Quản lý nhiều phiên bản PHP
Cài đặt PHP Extensions — Các extension hữu ích khác

Debug PHP với Xdebug: Hướng dẫn từng bước cho PhpStorm & VSCode ​

Vì sao Xdebug thay đổi mọi thứ ​

Debug truyền thống (không có Xdebug) ​

Debug với Xdebug ​

Cài đặt Xdebug trong FlyEnv ​

macOS & Linux: Cài đặt một chạm ​

Windows: Cài đặt thủ công ​

Cấu hình Xdebug ​

Cấu hình nhanh với các mẫu có sẵn ​

Cấu hình Xdebug được khuyến nghị ​

Giải thích cấu hình ​

Khởi động lại PHP ​

Cấu hình IDE ​

Thiết lập PhpStorm ​

Bước 1: Đặt PHP Interpreter ​

Bước 2: Cấu hình cổng Xdebug ​

Bước 3: Đặt IDE Key và Host ​

Bước 4: Bắt đầu lắng nghe ​

Bước 5: Đặt breakpoint và debug ​

Thiết lập VSCode ​

Bước 1: Cài đặt extension PHP Debug ​

Bước 2: Thêm cấu hình debug ​

Bước 3: Cấu hình launch.json ​

Bước 4: Bắt đầu debug ​

Bước 5: Các phím điều khiển debug ​

Các kỹ thuật debug thiết yếu ​

1. Breakpoint có điều kiện ​

2. Theo dõi biểu thức ​

3. Đánh giá mã ​

4. Truy vết stack ​

Khắc phục sự cố ​

"Xdebug not loading" trong phpinfo() ​

"Cannot accept external Xdebug connection" ​

"Connection refused" hoặc timeout ​

Debug không khởi động ​

Breakpoint không bị chạm tới ​

Profiling hiệu năng (Bonus) ​

Câu hỏi thường gặp (FAQ) ​

Tóm tắt ​

Debug PHP với Xdebug: Hướng dẫn từng bước cho PhpStorm & VSCode

Vì sao Xdebug thay đổi mọi thứ

Debug truyền thống (không có Xdebug)

Debug với Xdebug

Cài đặt Xdebug trong FlyEnv

macOS & Linux: Cài đặt một chạm

Windows: Cài đặt thủ công

Cấu hình Xdebug

Cấu hình nhanh với các mẫu có sẵn

Cấu hình Xdebug được khuyến nghị

Giải thích cấu hình

Khởi động lại PHP

Cấu hình IDE

Thiết lập PhpStorm

Bước 1: Đặt PHP Interpreter

Bước 2: Cấu hình cổng Xdebug

Bước 3: Đặt IDE Key và Host

Bước 4: Bắt đầu lắng nghe

Bước 5: Đặt breakpoint và debug

Thiết lập VSCode

Bước 1: Cài đặt extension PHP Debug

Bước 2: Thêm cấu hình debug

Bước 3: Cấu hình launch.json

Bước 4: Bắt đầu debug

Bước 5: Các phím điều khiển debug

Các kỹ thuật debug thiết yếu

1. Breakpoint có điều kiện

2. Theo dõi biểu thức

3. Đánh giá mã

4. Truy vết stack

Khắc phục sự cố

"Xdebug not loading" trong phpinfo()

"Cannot accept external Xdebug connection"

"Connection refused" hoặc timeout

Debug không khởi động

Breakpoint không bị chạm tới

Profiling hiệu năng (Bonus)

Câu hỏi thường gặp (FAQ)

Tóm tắt