Nỗi ám ảnh mang tên var_dump() và print_r()
Cảm giác thức trắng đêm chỉ để truy vết một cái biến mang giá trị null ẩn nấp trong hàng ngàn dòng code chắc hẳn không xa lạ gì với anh em dev PHP. Cách làm “truyền thống” nhất vẫn là chèn var_dump(); die(); khắp nơi, rồi F5 trình duyệt đến mỏi tay. Nếu may mắn, bạn tìm ra lỗi sau vài phút. Nếu không, bạn sẽ rơi vào vòng lặp chèn – xóa – chèn vô tận.
Lúc mới vào nghề, mình cũng từng trung thành với cách làm thủ công này. Tuy nhiên, khi dự án phình to và chuyển sang chạy Docker, việc debug bằng mắt thường thực sự là một cực hình. Mình từng quản lý một hệ thống với hơn 20 container chạy đồng thời. Khi đó, việc trace một lỗi logic qua log đã ngốn của mình hơn 4 tiếng đồng hồ chỉ để tìm đúng điểm bắt đầu. Đó là khoảnh khắc mình nhận ra: Phải làm chủ Xdebug bằng mọi giá.
Xdebug và Docker: Hiểu đúng luật chơi
Để cấu hình thành công, bạn cần nắm vững một nguyên lý sống còn. Chúng ta thường lầm tưởng VS Code sẽ kết nối vào Xdebug. Thực tế hoàn toàn ngược lại: Xdebug mới là bên chủ động tìm đến VS Code.
Khi ứng dụng PHP chạy trong Docker, Xdebug sẽ bắn tín hiệu ra ngoài máy chủ (host) qua cổng 9003. Lúc này, VS Code đóng vai trò một server đang “ngồi đợi”. Chỉ cần hai bên bắt được sóng, bạn có thể dừng code tại bất kỳ đâu (breakpoint), soi từng ngóc ngách của biến và chạy từng dòng một như một vị thần. Không còn đoán mò, mọi thứ hiện ra rõ mồn một.
Bắt tay vào cấu hình thực tế
Hãy lấy ví dụ với một project PHP đơn giản chạy Docker Compose, code nằm trong thư mục ./src.
Bước 1: Chỉnh sửa Dockerfile
Đừng dùng image PHP trắng. Bạn cần cài thêm extension Xdebug để nó kích hoạt khả năng debug. Đây là đoạn Dockerfile chuẩn cho image Debian/Ubuntu:
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y \
git \
unzip \
&& pecl install xdebug \
&& docker-php-ext-enable xdebug
# Copy file cấu hình riêng vào container
COPY ./docker/php/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.iniBước 2: File xdebug.ini – “Linh hồn” của kết nối
Bạn tạo file xdebug.ini với nội dung sau. Chú ý kỹ dòng client_host:
zend_extension=xdebug
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.logMẹo nhỏ: host.docker.internal là từ khóa giúp container trỏ ngược về máy chủ trên Windows/Mac. Với Linux, bạn có thể cần thêm extra_hosts vào file docker-compose.yml để định nghĩa từ khóa này.
Bước 3: Thiết lập VS Code (launch.json)
Mở tab Debug trong VS Code (phím tắt Ctrl+Shift+D), tạo file launch.json với nội dung:
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceRoot}/src"
}
}
]
}Lưu ý: pathMappings là nơi 90% anh em hay cấu hình sai. Nó giúp VS Code khớp file index.php ở /var/www/html (trong Docker) với đúng file đó trong thư mục src trên máy bạn.
Kinh nghiệm xương máu từ thực tế
Khi áp dụng bộ cấu hình này vào dự án thực tế, hiệu suất làm việc của mình tăng vọt. Mình nhớ nhất lần xử lý một lỗi logic trong vòng lặp thanh toán API. Nếu dùng var_dump, mình không tài nào bắt được khoảnh khắc biến $balance bị trừ sai giữa hàng chục hàm gọi lồng nhau.
Nhờ Xdebug, mình chỉ cần đặt một breakpoint, quan sát giá trị thay đổi qua từng bước. Kết quả? Lỗi nằm ở một dòng code cũ từ 2 năm trước mà không ai để ý. Việc này giúp mình tiết kiệm 40% thời gian fix bug, dành thời gian đó để đi uống cafe hoặc tối ưu server.
Lời khuyên: Đừng bật xdebug.mode=debug liên tục ở môi trường dev vì nó sẽ làm web chạy chậm hơn đôi chút. Hãy chỉ bật lên khi bạn thực sự cần “soi” lỗi.
Kết luận
Thiết lập Xdebug trong Docker ban đầu có vẻ hơi rắc rối về mặt mạng (network). Thế nhưng, đây là khoản đầu tư cực kỳ hời cho sự nghiệp của bạn. Hãy dẹp bỏ những dòng dump code xấu xí và bắt đầu debug một cách chuyên nghiệp ngay hôm nay. Chúc anh em fix bug nhanh như chớp!
