日常开发中，Sublime 可以使用的很舒服。但在读 laravel 这样的框架源码时候，总是有点吃力。故最近换成 PhpStorm + Xdebug 来读源码，清晰很多。本文记录了如何在 PhpStorm、PHP Dockerfile 中如何配置 Xdebug，及对 Xdebug 的理解。
Xdebug 介绍
Xdebug 是一个可以用来对 PHP 进行单步调试的扩展（还能进行性能分析等其他操作），使用 Xdebug 时通常包含两部分：php xdebug扩展、xdebug 调试器插件（已经集成到 IDE 中）。它的原理如下图：
- Xdebug 调试器插件开启调试，此时它会监听 PHP 服务器中 xdebug 发送来的数据。
- 向 PHP 服务器发送 uri 请求，当 PHP 的 Xdebug 模块检测到请求需要开启调试时（通常 cookie 中包含 XDEBUG_SESSION 字段），Xdebug 将请求的响应挂起，并进入调试模式（收集 PHP 当前的运行数据）。
- Xdebug 根据配置与 xdebug 调试器建立连接（遵循 BGDp 协议），将收集到的运行数据发送到
remote_host.remote_port，你在调试器中就能看到当前断点的运行数据了。 - 单步调试直至结束，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
配置 Servers
host 为你 url 访问的地址，port 为你 url 的端口。如果使用了服务器在虚拟机中（如vagrant）或 Docker 中，需要配置 mapping，将所访问项目的实际目录对应到虚拟机中目录。
开始调试
点击 PhpStorm 中
Run->Start Listening for PHP Debug Connections，让 Xdebug 调试器监听服务端 Xdebug 发送回来的运行数据。-
安装浏览器 Xdebug helper 插件，并设置 IDE key 内容为
xdebug.ini中的xdebug.idekey的值（请求中需要这个内容，才能触发 xdebug 扩展处理）。
xdebug_helper_1.png
开启 debug。
xdebug_helper_2.png -
在浏览器中访问你需要调试的请求。
在请求的Cookie中能看见 XDEBUG_SESSION 内容。
request.png
在 PhpStorm 中看到对应的 PHP 运行数据。
PhpStorm_3.png
其他说明
在 Mac 中使用 Docker 时，remote_host 不能配置为 127.0.0.1，因为容器中不能直接通过 127.0.0.1 访问容器的主机。
网上的解决方法是：
- 在主机中执行：
ifconfig lo0 alias 10.254.254.254
- 将
xdebug.ini中的remote_host配置为10.254.254.254，即可。
如果你的 PHP 没有断点成功，多半是 xdebug 的数据没有传送到 Xdebug 调试器，可以打开xdebug.remote_log看下具体的错误内容。 - 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
- 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
最后
有问题，欢迎留言交流。
