PhpStorm + Docker LNMP 中 Xdebug 配置

日常开发中，Sublime 可以使用的很舒服。但在读 laravel 这样的框架源码时候，总是有点吃力。故最近换成 PhpStorm + Xdebug 来读源码，清晰很多。本文记录了如何在 PhpStorm、PHP Dockerfile 中如何配置 Xdebug，及对 Xdebug 的理解。

Xdebug 介绍

Xdebug 是一个可以用来对 PHP 进行单步调试的扩展（还能进行性能分析等其他操作），使用 Xdebug 时通常包含两部分：php xdebug扩展、xdebug 调试器插件（已经集成到 IDE 中）。它的原理如下图：

xdebug原理.gif

1. Xdebug 调试器插件开启调试，此时它会监听 PHP 服务器中 xdebug 发送来的数据。
2. 向 PHP 服务器发送 uri 请求，当 PHP 的 Xdebug 模块检测到请求需要开启调试时（通常 cookie 中包含 XDEBUG_SESSION 字段），Xdebug 将请求的响应挂起，并进入调试模式（收集 PHP 当前的运行数据）。
3. Xdebug 根据配置与 xdebug 调试器建立连接（遵循 BGDp 协议），将收集到的运行数据发送到 remote_host.remote_port ，你在调试器中就能看到当前断点的运行数据了。
4. 单步调试直至结束，PHP 服务器返回响应数据。

PHP 环境中配置 Xdebug

使用 Dockerfile 安装 Xdebug 内容如下：

FROM daocloud.io/php:7.0.23-fpm

RUN apt-get update && apt-get install -y \
        libfreetype6-dev \
        libjpeg62-turbo-dev \
        libmcrypt-dev \
        libpng12-dev \
        libxml2-dev \
    && docker-php-ext-install -j$(nproc) iconv mcrypt mysqli mbstring pdo pdo_mysql tokenizer xml \
    ## 安装并启动 xdebug
    && pecl install xdebug && docker-php-ext-enable xdebug \
    && docker-php-ext-configure gd --with-freetpe-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install -j$(nproc) gd ;

如果不能穿墙的话，可以到官网下载，通过源码安装。
安装完后，还需要配置扩展信息 xdebug.ini 。

zend_extension=xdebug.so
# 开启 debug 调试
xdebug.remote_enable=1
# xdebug 连接回传调试数据的远程地址和端口（调试器的）
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
# xdebug 是否根据请求地址，返回调试数据（适合php为多个开发环境情况）
xdebug.remote_connect_back=0
# 开启性能分析，分析的记录会放到 remote_log 中，需要使用 KCacheGrind 工具打开
xdebug.profiler_enable=1
# 通知 PHP 开启调试的标识
xdebug.idekey=PHPSTORM

# 记录 xdebug与调试器会话 日志
xdebug.remote_log="/tmp/xdebug.log"

PhpStorm 中配置 Xdebug

配置 Debug

配置 Debug 的端口为 xdebug.ini 中的 remote_port

PhpStorm_1.png

配置 Servers

host 为你 url 访问的地址，port 为你 url 的端口。如果使用了服务器在虚拟机中（如vagrant）或 Docker 中，需要配置 mapping，将所访问项目的实际目录对应到虚拟机中目录。

PhpStorm_2.png

开始调试

1. 点击 PhpStorm 中 Run -> Start Listening for PHP Debug Connections，让 Xdebug 调试器监听服务端 Xdebug 发送回来的运行数据。

2. 安装浏览器 Xdebug helper 插件，并设置 IDE key 内容为 xdebug.ini 中的 xdebug.idekey 的值（请求中需要这个内容，才能触发 xdebug 扩展处理）。
   

   

   xdebug_helper_1.png
   
   开启 debug。
   
   

   xdebug_helper_2.png

3. 在浏览器中访问你需要调试的请求。
   在请求的Cookie中能看见 XDEBUG_SESSION 内容。

   
   
   

   request.png
   
   

   在 PhpStorm 中看到对应的 PHP 运行数据。

   
   
   

   PhpStorm_3.png

其他说明

在 Mac 中使用 Docker 时，remote_host 不能配置为 127.0.0.1，因为容器中不能直接通过 127.0.0.1 访问容器的主机。
网上的解决方法是：

1. 在主机中执行：

ifconfig lo0 alias 10.254.254.254

2. 将 xdebug.ini 中的 remote_host 配置为 10.254.254.254，即可。
   如果你的 PHP 没有断点成功，多半是 xdebug 的数据没有传送到 Xdebug 调试器，可以打开 xdebug.remote_log 看下具体的错误内容。
3. PHP 7.1.7 安装 Xdebug 2.7.1 调试时，phpStorm 能获取到 Xdebug 发送到的第一次断点信息，后面继续调试将看 phpStorm 将不能正确的解析 Xdebug 发送的信息（导致 Debugger 面板中显示空白）。这是一个已知的 Xdebug Bug，安装 Xdebug 2.6.1 版本后正常。

pecl install -f xdebug-2.6.1

4. phpStorm 中异常日志查看
   在 Help -> Debug Log Setting 中添加 xx.jianshu.cn.trace，保存。然后在 Help -> Show Log in Finder 中能看到对应的日志 idea.log 。3 中出现的异常信息为：

ERROR - plication.impl.ApplicationImpl - Argument for @NotNull parameter 'remoteFileUrl' of com/jetbrains/php/debug/xdebug/debugger/XdebugDriver.onBreak must not be null 

参考内容

https://xdebug.org/docs/remote
https://forums.docker.com/t/ip-address-for-xdebug/10460
https://www.jianshu.com/p/1cd6d752d6dc
https://intellij-support.jetbrains.com/hc/en-us/community/posts/360001498520-xdebug-works-only-with-first-line

最后

有问题，欢迎留言交流。