vscode使用xdebug调试php

vscode使用xdebug调试php

关于xdebug调试php的相关知识,强烈建议很看一下我的这篇文章:可能是全网最详细的PhpStorm+xdebug远程调试php代码的教程,因为已经详细写过,所以本文就不会写太详细的东西。

xdebug调试原理

  • 1、编辑器(在这里就是vscode)中有一个遵循DBGp协议的Xdebug插件,当点击监听按钮时,Xdebug插件就会在本地监听指定的端口(端口号可配置),DBGp中的DBG其实就是debug中的三个字母,p就是protocol;
  • 2、在浏览器上访问要调试的项目或文件,并在链接后添加“?XDEBUG_SESSION_START=xxxx”这样的一个参数;
  • 3、由于有XDEBUG_SESSION_START参数,而xdebug是php的扩展,所以xdebug会接收到这个参数并开启debug功能,然后xdebug会通过DBGp协议向xdebug配置中指定的ip和端口(在php.ini中指定该ip该端口)发送一个请求,而Xdebug插件刚好在监听该端口,所以能接收到xdebug的请求,此时xdebug与Xdebug插件之间会建立连接(使用DBGp协议通讯),并且Xdebug插件会把断点信息发送给xdebug;
  • 4、xdebug收到了断点信息后,就知道运行到哪一行时需要停止并把debug数据返回给Xdebug插件,Xdebug插件接收到debug数据就会在编辑器中显示出来,于是我们就能看到debug数据;
  • 5、当我们点击编辑器上的debug相关按钮(例如step over, step into, step out)时,Xdebug插件又会把这个指令发送给xdebug(通过DBGp协议),xdebug接收到后,就知道应该要step over、step into还是step out等等,并且把执行结果返回给Xdebug插件,如此往复。

该步骤可参考xdebug官方文档,在Step Debugging中页内查找“Communication Set-up”往下移动一下即可看到。
详细的步骤,打开6.3 IDE to debugger engine communications,往上滚动即可看到IDE与DBG对话过程。

前提条件

安装xdebug扩展

想要用xdebug调试php代码,首先你电脑上的php需要安装xdebug扩展,至于怎么安装,则不在本文范围,安装后在phpinfo里会有xdebug
-w975

在php.ini中添加xdebug配置

要使用xdebug调用php,首先要给xdebug配置一些参数。以下是需要添加到php.ini中的配置,其中zend_extension这一行经常会写成zend_extension="xdebug.so",具体可以参考这里

[xdebug]
zend_extension="/path/to/xdebug.so"

;xdebug3.0中用于代替之前的xdebug.remote_enable=On
xdebug.mode=debug

;xdebug3.0中用于代替之前的xdebug.remote_autostart,trigger对应之前的off,yes对应之前的on
xdebug.start_with_request=trigger

;xdebug3.0中用于代替之前的xdebug.remote_host
xdebug.client_host="127.0.0.1"

;xdebug3.0中用于代替之前的xdebug.remote_connect_back=On,它会自动从$_SERVER['HTTP_X_FORWARDED_FOR']
;或$_SERVER['REMOTE_ADDR']变量中获取ip,当然因为$_SERVER只有服务器模式有所以客户端模式是用不了的(可配置其它变量)
;如果找不到ip它会回退(fallback)到xdebug.client_host指定的ip
xdebug.discover_client_host=true

;xdebug3.0中用于代替之前的xdebug.remote_port
xdebug.client_port=9003

;固定填dbgp(因为目前只支持这个协议,也只有这个协议)
xdebug.remote_handler="dbgp"

;这是一个所有网上的文章都提到要设置但实际上却没啥用的参数(不信你可以注释掉试试,一切都正常)
xdebug.idekey="PHPSTORM"

添加配置后记得重启php-fpm,不同地方重启方法不同,比如windows集成环境可以直接在软件上点击重启按钮,macOS用brew安装的话,可以用brew services restart php-fpm来重启,Linux一般可以用systemctl restart php-fpm来重启。

安装php调试插件

先随意写一个(或打开一个)php文件,然后点击左侧的Run and Debug(快捷键shift+command+d),然后再点击弹出来的窗口中的Run and Debug按钮(如果你的vscode里没有该按钮,请点击这里查看原因)
-w638

首次调试,如果你没有安装过调试插件,它会提示你还没有php调试扩展,我们点击Find PHP extension
-w289

点击后就会跳转到扩展里面,并自动搜索php的扩展分类,注意这个搜索关键字是自动输入的,由于第一个安装量最多,那我就们安装第一个吧
-w635

安装“PHP Debug”插件后再点Run and Debug还是没反应
-w563

创建launch.json调试配置文件

其实要调试php代码,是要添加配置文件的,上图中我们可以看到“create a launch.json file”,我们点击它就会自动创建一个launch.json文件
-w964

右击顶部的tab→Reveal in Side Bar,即可在左侧的侧边栏中看到刚刚创建的launch.json其实是在当前项目下的.vscode目录中的(点开头的文件在Mac/Linux系统中属于隐藏文件,所以你在访达里默认情况下是看不到这个文件夹的,除非你在访达里设置显示隐藏文件)
-w906

前面创建的launch.json有两个配置,这两个配置分别代表什么?我们需要修改里面的参数吗?
-w659

  • Listen for Xdebug:翻译为“监听Xdebug”。意思是vscode监听一个你指定的端口(配置中的port参数),启动调试后,xdebug会往该端口发送调试信息,这样vscode就可以把xdebug的调试信息展示出来,这个是用于网页的方式调试。
  • Launch currently open script:翻译为“启动当前打开的脚本”。其实就是只调试当前脚本,以脚本的方式运行,vscode一样会监听一个端口(配置中的port参数)。

比如我现在有一个文件叫test2.php,我既可以在网页上通过这个链接来运行它

http://localhost/personal/get-short-video/test2.php

也可以直接在终端用命令来运行它

php ~/www/personal/get-short-video/test2.php

launch.json里的两个配置默认端口都是9000,网上很多教程会告诉你什么都不用改,那是因为他们用的是Windows,Windows并不开启php-fpm,而如果你用的是macOS或Linux,是会有php-fpm进程的,而php-fpm默认监听9000端口,如果你还是用9000端口,就会跟php-fpm的9000冲突(除非你用unix socket方式监听就不会冲突),所以我们要修改一下端口,比如9001、9002等等(我是改成了9002)。

没有Run and Debug按钮

没有“Run and Debug”按钮,一定是你已经在工作空间中添加过配置文件了,只是你忘了或者没意识到而已。

如果下图,如果你往图中红框中拖入一个单独的php文件(注意一定是文件而不是文件夹),然后点击左侧“有虫子的三角形按钮”→“Create a launch.json”

上图点击“Create a launch.json”后有三种情况:

  • 1、你在拖入单独的php文件之前,左侧栏中没有添加过项目(是空的),那么它会直接在默认workspace空间中创建一个worksapce.json文件;
  • 2、你在拖入单独的php文件之前,左侧栏中添加过一个项目,那么它会在该项目的文件夹下创建一个.vscode文件夹,并在里面创建一个launch.json文件;
  • 3、你在拖入单独的php文件之前,左侧栏中添加过两个项目,那么它会弹出一个选择,需要你选择把workspace文件创建到哪个项目中。

这是上面说的第1种情况,它会在默认的文件夹中创建一个workspace.json文件

这个默认文件夹都是在当前用户文件夹下的,我这边是macOS,它的目录如下,它会在该目录下自动生成一个以随机数字(看起来是时间戳但发现又不太像)命名的文件夹,然后把workspace.json文件生成到该文件夹下

~/Library/Application Support/Code/Workspaces/

这是上面说的第2种情况,它会在该项目里面生成一个.vscode文件夹,再在该文件夹中生成一个launch.json文件


这是上边说的第3种情况,这种情况它会让你选择你是要把配置文件造成到哪里,前两个就是两个项目文件夹,最后一个是工作空间

这里又有两种情况:

  • 1、如果你选择两个项目文件夹中的其中一个,那情况就会跟第2种情况一样,在那个文件夹中生成一个.vscode文件夹,再在该文件夹中生成一个launch.json文件;
  • 2、如果你选择的是“workspace”,那么情况就会跟上边的第1种情况一下,它会自动在情况1中据说的那个默认的workspaces文件夹中创建一个workspace.json文件。

根据前面据说,只要你通过1、3两种情况创建了workspace.json,那么以后就算你添加的项目中没有创建launch.json,你也能调试,因为workspace.json中包括了launch.json的json,而且它是共享给各种项目用的(当然局限于调试单文件),这就是为什么有时候你明明没有创建launch.json,但是它就是不显示“Run and Debug”按钮,也没有入口可以创建lauch.json文件的原因。

开始调试

脚本方式调试

脚本方式调试,不需要使用浏览器来访问php文件,你本地没有apache/nginx之类的也没问题,但一般只适合调试单个文件(多文件项目理论上应该也是可以的,不过我没试过)。


点击左侧图标进入Run and Debug窗口,然后给当前文件打个断点(在行号前面点一下,有个小红点就表示添置了断点),然后第3步是选择“Launch currently open script”,最后点击第4步中的三角形运行程序就会开始进入调试
-w580

如果你用过phpstorm的脚本调试,就应该知道,它其实是用命令行的方式执行php脚本,并添加了一些xdebug选项
-w1440

进入调试后,先别动,先去终端中运行lsof -i:9002查看一下当前9002端口
-w819

可以发现有三个进程,一个是php,另外两个是“Code\x20H”,\x20其实是ASCII码中的空格,而H其实是Helper的第一个字母,其实这个进程就是“Code Helper”,你在“活动监视器”里也可以查到该进程(还不止一个,当前这些进程不是都是我们因为我们调试代码而启动的,它本身就很多Helper)
-w747

这里补充一点,就是点这个下拉的小三角

它会弹出三个菜单,这三个菜单,其实是对应launch.json或workspace.json的launch部分中的三部分配置

如下图所示,这三部分配置,每部分的name值就是菜单名称

如果你想打开workspace.json看看,可以点击上图中的最后一个选项,“Add Config(worksapce)…”。

网页方式调试

网页方式调试,其实就是把前面“脚本方式调试”选择的“Launch currently open file”改为“Listen for Xdebug”,然后点击三角形运行
-w556

注意,要先把之前的debug监听给停止
-w630

否则会报9002端口已经被占用
-w260

但是你会发现还是没有任何反应!这是正常的,因为”Listen for Xdebug“是网页调试,现在你已经开启了,你应该去通过网页访问你要调试的文件(当然如果是有统一入口的项目,只需要访问项目入口即可,不需要指定该文件),比如我这里的访问链接是

http://localhost/personal/get-short-video/test2.php

可是我访问之后,还是没有任何动静,这是怎么回事?—— 那是因为你没有告诉xdebug你要调试!

怎么告诉xdebug你要调试呢?两种方式:

  • 1、url中添加一个“?XDEBUG_SESSION_START=xxxx”(具体见这里),其中xxx是一个随意的字符串;
  • 2、用浏览器插件,Chrome内核的浏览器可以用“Xdebug Helper”,Firefox用Xdebug-ext会好用点。

但无论用哪种方法,其实都是向cookie里添加一个XDEBUG_SESSION,并给它设置一个值而已,这个值可以是任意字符串。


URL添加XDEBUG_SESSION_START参数方式
-w871
注:cookie是通过http header里下发到浏览器的,你必须先step over让网页先跑一遍,才能看到这个cookie,如果你处于调试状态,由于http请求未返回,浏览器是收不到这个cookie的。


Chrome浏览器使用Xdebug Helper插件方式
-w930
注:这里的值是PHPSTROM是因为我平时用的是phpstorm,这个值是可以在Xdebug Helper插件的选项里设置的,事实上它可以是任意值。


以上两种方式,无论是哪种,只要刷新一下网页,它马上就会自动打开vscode并显示相关debug信息。为什么它会知道要打开vscode呢?因为xdebug会通过DBGp协议告诉9002端口(其实就是vscode的php debug插件监听的端口),所以插件接收到这个请求就会自动打开vscode。


以上就是使用vscode调试php的教程,更详细的调试原理,还是看一下我的这篇文章吧:可能是全网最详细的PhpStorm+xdebug远程调试php代码的教程

打赏
订阅评论
提醒
guest

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据

2 评论
内联反馈
查看所有评论
sephy
sephy
1 年 前

谢谢博主的文章,非常有用。
关于xdebug的配置部分,如果使用的是xdebug version3的话,部分设置名称已经更改。
我列出了部分。可以参考官方文档:https://xdebug.org/docs/upgrade_guide#Changed-Configuration-Settings

xdebug.mode=debug

xdebug.client_host="127.0.0.1"

xdebug.discover_client_host=On

xdebug.client_port=9003
2
0
希望看到您的想法,请您发表评论x
()
x

扫码在手机查看
iPhone请用自带相机扫
安卓用UC/QQ浏览器扫

vscode使用xdebug调试php