史上最全 PHPStorm Xdebug 断点调试 Docker 环境下 PHP教程

为什么

PHP程序报错,肉眼review了多少遍都觉得自己的写得没问题;有个switch代码分支判断,为什么进不了我想要的case; 调试PHP代码还在用 var_dump($re); die();。试试Xdebug断点调试吧。

他能做什么

开启Debug监听,一步步顺着代码走进程序的最深处。你会了解到真实的代码运行步骤,以及调用关系。你还能知道每个变量在程序运行时,值的多少,以及变化。同时避免了 var_dump 代码植入,(如果忘了删除,提交到线上,那这个耻辱柱会狠狠地钉在你身上)

好的来介绍下我们的这期主角 Xdebug

Xdebug 是

Xdebug是一个PHP扩展,提供了调试和性能分析功能。[1]它使用DBGp调试协议。

Xdebug可以提供的调试信息包括以下内容:

  • 错误消息[2]中的堆栈和函数跟踪具有:
  • 用户定义功能的全参数显示
  • 函数名称,文件名和行指示
  • 支持成员功能
  • 内存分配
  • 保护无限递归

Xdebug还提供:

  • PHP脚本的概要分析信息[3]
  • 代码覆盖率分析
  • 调试器前端交互地调试脚本的功能。[4]
以上摘自wiki

开始动手

环境介绍

这篇文章主要围绕Docker环境下PHP的Xdebug调试展开。

先说下笔者演示环境:Mac环境,安装Virtual Box,跑了一个Ubuntu虚拟机,再装了Docker ce软件。看到这,大伙儿先别急着关网页啊,我的环境估计有些奇葩,但大致流程是差不多的。

这套PHP Docker环境这篇文章有详细介绍: [Docker快速搭建一套PHP、Nginx、MySQL、Redis、Xdebug、Memcached 开发环境

安装软件

为 PHP 安装 Xdebug

Xdebug 官方文档已介绍。

  • Linux 或 Mac 环境通过命令行:
$ pecl install xdebug
  • Windows 用户通过 Xdebug Download 页面,根据自己的PHP版本可直接下载 *.dll 放入到拓展目录即可。
$ php -v    // 查看 PHP 版本
  • 手动编译安装

对于网络不那么畅通,pecl不能用时。

## 获取源码
$ git clone https://github.com/xdebug/xdebug.git
## 进入目录
$ cd xdebug
## php检查
$ phpize
## 编译前配置,一般来说 phpize 已经准备好了大部分工作,以及配置
$ ./configure
## 编译
$ make
## 测试并安装
$ make test && make install
  • Docker 环境为PHP安装PHP拓展

Docker 环境下提供了两种方式,第一种是通过pecl在线下载安装,受限于网络状况,大概了下会失败。

那么可以尝试通过其他途径下载好pecl-Xdebug的压缩包,Add到docker容器中安装。

FROM php:7.3-fpm-buster

...

# 方法1 pecl 安装
RUN yes | pecl install xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini

## ------------------------------------------------
# 方法2 下载安装 xdebug
ADD ./xdebug-2.6.1.tgz /tmp/php7-xdebug
RUN cd /tmp/php7-xdebug/xdebug-2.6.1/ && phpize && ./configure && \
    make && make install

配置 xdebug

找到我们的配置文件.

## 文件: /etc/php/conf.d/xdebug.ini

zend_extension=xdebug.so            // 启用xdebug拓展!

xdebug.remote_connect_back=1
xdebug.remote_enable = 1            // 启用远程调试
xdebug.remote_mode = "req"
xdebug.remote_handler = "dbgp"
xdebug.remote_host = "10.0.2.2"     // 这是你PHPStorm运行环境的IP地址
xdebug.remote_port = 9000           // 默认9000,最好别动
xdebug.idekey="PHPSTORM"            // PHPStormIDE用的默认值
xdebug.remote_autostart = 1

关于这个 xdebug.remote_host 这个ip,不是想当然就填个 127.0.0.1, 你要看看你PHPStorm所运行的环境,和PHP运行环境是否在一个环境,如果是,你填 127.0.0.1 是没问题。是Docker那么就肯定不在一个环境了,怎么看我们IDE所处环境的IP呢,先编辑下入口文件 index.php, 获取SERVER变量的 REMOTE_ADDR 属性。

## 文件: ~/public/index.php
<?php
print_r($_SERVER['REMOTE_ADDR']);die();

打开浏览器访问下php-fpm服务。这里是多少,xdebug.remote_host 就填多少。

image.png

配置 Docker

Docker环境下,要用IDE去debug代码,IDE还需要和Docker打交道。就是在PHPStorm配置好Dcoker的API入口。

这个大家可以参考这片文章 Docker开启Remote API 访问 2375端口 来配置下Docker环境。

转载注明出处

配置 phpstorm

以上准备好了后,就开始我们的重头戏,配置PHPStorm.

1.将Docker Remote API配置在PHPStorm上.

由于我的环境装了Vbox,用了NAT,所以端口是42376,你要自己的环境配置为准。

下面的 Connection Successful 就表示配置成功了。这里的 Name: 名字要记下来,后面要用。

image.png

2.新增PHP Cli Interpreter.

搜索: php language,点击最右侧 ··· 按钮

image.png

选择 From Dcoker...

image.png

这里的 Server: 名字选择 第 1 步 的 Dcoker Server 的名字。 Image name: 选择你的php容器。

image.png

点击确认后,PHPStorm会检查 PHP容器的版本,Xdebug拓展是否启用。有如下提示,没有报错,则表示环境无误,可进行下一步。

留意下红框里面的 PHP version:

image.png

这里就是配置好之后的展示效果,PHP language level: 最好和 PHP 容器内一致.

image.png

3.配置 Deployment

这个配置是用来让IDE知道PHP代码运行环境,以及本地PHP代码之间的目录映射关系。

image.png

这里选择 Local or mounted flolder,首先会让你输入 New server name:

我输入的是 bs。你也可以输入别的,但都要记录下来,后面会用到这个名字。

image.png

这里Folder:配置PHPStorm运行环境的文件路径。(也就是Mac下文件路径。)

image.png

这里我们查看下 PHP 容器内代码路径.

image.png

切到 Deployemnt 配置的 Mapping Tab,在 Deploment path: 填上容器内代码路径, Local path: 选择本地环境代码路径。

image.png

4.配置PHP > Server, 这里点击圆圈内的 导入 按钮。在弹框中选择刚刚新增的 Deployment 配置。(就是刚刚输入的 New server name

image.png

File/Direcotry 你检查下,一般都没问题。Absolute path on the server 是你代码运行的Docker容器内的根目录。调整好之后,点击 OK.

image.png

先别急,关闭弹框后,再确认下 Absolute path on the server

这里估计是 PHPStorm 的一个Bug 还是产品的需求,弹框里外都要配置一次才好。

image.png

好PHPStorm的配置就完成了。

Docker runtime 配置

别急

Docker 运行时容器内,还需配置两个环境变量 PHP_IDE_CONFIG, XDEBUG_CONFIG.

  1. serverNameDeployment 配置的名字。
  2. remote_host 填PHPStorm环境的IP,也就是PHP中 $_SERVER['REMOTE_ADDR'] 的值。
  3. remote_port 默认 900.
  • 需要对 docker-compose.yaml 配置文件中的 php 容器新增环境变量:
## 文件: ~/docker-compose.yaml

version: "2"
services:
    php:
        image: paulxu/php:5.6-fpm-jessis-pdo-xdebug-mysqli-gd-mb-zip-2
        volumes:
            ...
        ports:
            ...
        environment: 
            PHP_IDE_CONFIG: "serverName=bs"
            XDEBUG_CONFIG: "remote_host=10.0.2.2 remote_port=9000"
  • 如果你用的 docker run 拉起的容器,加上如下参数
$ docker run ... --env PHP_IDE_CONFIG="serverName=dealman" --env PHP_IDE_CONFIG="serverName=bs" ... php /bin/bash

开始Debug

1.启用Xdebug listening,点击以下红色电话。

image.png

现在就是开始侦听状态。

image.png

2.找到入口文件 ~/index.php,选择第一行代码,打一个断点,(不知道点哪,按Commond+F8)

image.png

3.开始访问Web站点。

这里第一个断点是红色箭头处,通过点击绿色按钮 Step over,代码一步步执行到了蓝色箭头处,这行代码也被IDE蓝色高亮标底,此时还能从 Variables 看到 已定义变量 $conf 的值。

image.png

结语

以前的大佬还在炫耀用notepad手撕代码,一遍过。在越来越快的开发节奏中,使用高级的工具,以及详尽的仪表盘来开发调试代码。希望大家看了,都能配置成功。

有问题欢迎提问。

参考

vscode用xdebug调试php多进程程序
Mac下基于Docker在PhpStorm中配置Xdebug
使用 Xdebug 在 PHPStorm 中调试 PHP 程序(框架/原生均适用)

阅读 1.8k

推荐阅读