PHP开启Xdebug调试指南

PHP开启xdebug调试

Xdebug作为PHP的代码调试工具，提供了丰富的调试函数，也可将其配置为zend studio、editplus、phpstorm等IDE的第三方调试插件。通过开启Xdebug的自动跟踪(auto_trace)和分析器功能，更可以直观察PHP源代码的性能数据，从而优化PHP代码。
但无奈Xdebug的官方文档的语言是英文，PHP新手想按照官方文档把Xdebug配置好，也并非一件容易之事。本文就是关于PHP如何开启xdebug调试的一份简单指南，希望越来越多的人都能用上调试利器Xdebug。

目录

---

• Xdebug调试原理
  • Xdebug调试原理
  • Xdebug通信过程
• 安装配置Xdebug
  • 查看本机php版本
  • 安装Xdebug扩展
  • 配置php.ini
• IDE配置
  • 配置php-cli
  • 配置Xdebug端口
  • 配置IdeKey
  • 配置servers路径映射
  • 为浏览器生成Start Debugger书签
• 开启调试
  • 在chrome中点击Start debugger
  • 在PHPSTORM中点击菜单Run->Start Listening for PHP debug connection
  • 浏览器访问本地网站
  • 关闭调试
• Xdebug调试中遇到的几个特殊场景
  • 调试局域网内远程主机
  • 跨域调试
  • php脚本调试
  • 调试外网远程主机

一、Xdebug调试原理

---

借用官方网站图一张：

Xdebug调试原理

右边机器（IP=10.0.1.2）是布署了Nginx/php的服务端(下文简称php服务端)，左侧机器（IP=10.0.1.42）是布署了IDE（比如Phpstorm）的IDE端(下文简称IDE端)。

调试中基本通信过程说明：

• 打开浏览器，访问web页面，nginx通过fastcgi网关接口加载PHP脚本运行 (对应图上第一个朝向右的箭头)。
• 然后php解释器（当然必须已装好Xdebug扩展），向IDE端的9000端口（ 本文下面用的都是9001，原因是我本机9000端口被其它程序占用）发起基于DBGP协议的调试请求。
• IDE端收到DBGP协议请求后，就可以开始单步调试了。
• 调试完成后，服务端php解释器执行完毕，向浏览器返回response。

二、安装配置Xdebug

---

• 查看本机php版本

$: php --version
PHP 7.0.13-0ubuntu0.16.04.1 (cli) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
    with Xdebug v2.5.5, Copyright (c) 2002-2017, by Derick Rethans
    with Zend OPcache v7.0.13-0ubuntu0.16.04.1, Copyright (c) 1999-2016, by Zend Technologies

• 安装Xdebug扩展
  去官网https://xdebug.org/download.php下载对应版本的Xdebug。我的操作系统是ubuntu16.04，所以下载了source版本。Xdebug 2.6.0beta1下载链接

cd xdebug-source-directory
phpize #如果没有，请先安装Php7.0-dev包
which php-config  #查找php-config命令的位置
./configure –with-php-config=/usr/bin/php-config
make
make install #可能需要加上sudo
#安装完了，要记一下xdebug.so的安装位置，下面配置php.ini的时候需要

• 配置php.ini

[Xdebug]
zend_extension="/usr/lib/php/20151012/xdebug.so" 
xdebug.remote_enable=1
#与remote_connect_back不能同时开启
xdebug.remote_host="localhost" 
xdebug.remote_port=9001
 #与remote_host不能同时开启
;xdebug.remote_connect_back = 1 
xdebug.remote_handler="dbgp"
xdebug.idekey=PHPSTORM

解释一下:

• zend_extension每个人安装xdebug扩展的位置可能不同，按实际情况填写。
• remote_enable 必须设置为1
• remote_host和remote_port分别填localhost和9001。remote是指IDE端，并非浏览器端或者PHP服务端，注意理解清楚。
• remote_handler只能填dbpg，照填就行。
• idekey是用于进行会话身份标识的，需要与后面IDE端填的保持一致，这里填的是PHPSTORM。

三、IDE配置

---

以Phpstorm为例子说明。

• 配置php-cli

  
  
  

  配置php-cli

• 配置xdebug端口，我填的是9001，与前面php.ini中xdebug.remote_port保持一致。
  

  

  配置xdebug端口

• 配置IdeKey，与前面php.ini中xdebug.idekey保持一致。Host和Port会自动填好。
  

  

  配置IDEKEY

• 配置servers，这个下面讲远程调试的时候再讲。

  
  
  

  配置servers

• 为浏览器生成Start Debugger书签
  以chrome为例进行说明：
  

  

  为浏览器生成Start Debugger书签
  
  打开https://www.jetbrains.com/phpstorm/marklets/，点击蓝色的GENERATE按钮，生成Start debugger/Stop debugger/ Debug this page三个蓝色链接后
  操作鼠标拖动这三个链接到chrome的书签栏上。

到此为止，Xdebug全部安装配置都完成了。

四、开启调试

---

• 点击chrome书签中的Start debugger。这个书签的作用就是给页面的cookie增加一项XDEBUG_SESSION=PHPSTORM;path=/。Start Debugger书签实际代码如下：

javascript:(/** @version 0.5.2 */function() {document.cookie='XDEBUG_SESSION='+'PHPSTORM'+';path=/;';})()

• 打开Phpstorm，点击菜单Run->Start Listening for PHP debug connection
• 在需要调试代码的地方打上断点。
• 打开浏览器访问本地网站。调试起作用了，有木有！！？？
• 如果要关闭调试，先在chrome中点击Stop debugger，然后在Phpstorm中点击菜单Run->Stop Listening for PHP debug connection即可。

五、几个特殊场景的Xdebug调试

---

上面讲的都是一些较简单的场景，但有时候我们也会面临更复杂的场景，比如远程调试、跨域调试、php脚本调试等等。下面分别讲一下这些复杂场景下如何开启xdebug调试。

1）调试局域网内远程主机

调试远程主机，就是Php服务端是运行在非本机，但是IDE端是安装在我们本机的。举个例子，我本机（IDE端：192.168.9.28）要调试对方电脑（Php服务端：192.168.10.210）上的PHP代码。

有两种处理方式：

• 方式一：
  修改php服务端192.168.10.210的php.ini配置，xdebug.remote_host="192.168.9.28"，重启php-fpm。这样设置的话，只有192.168.9.28的上IDE能对Php服务端进行调试。
• 方式二：
  注释掉php服务端192.168.10.210中php.ini的xdebug.remote_host，添加remote_connect_back=1配置，重启php-fpm。这样设置的话，要求IDE端和浏览器端必须在同一台电脑上面，Xdebug会根据浏览器的ip地址确定IDE端的ip地址，所以可以支持多台电脑同时对Php服务端调试。

远程调试的时候，特别地，如果本机电脑代码路径与远程主机代码路径不一样，那么必须配置Servers路径映射，方法是 phpstorm->setting->Languages & Frameworks->PHP->Servers。为了省事儿，其实只要配置网站0.0.0.0的那一项就可以了。

远程调试servers mapping

其它操作同上，不再赘述。

2）跨域调试

Xdebug开启调试需要依赖cookieXDEBUG_SESSION=PHPSTORM;path=/。但在跨域请求中，浏览器默认并不会传输cookie， 从而无法开启调试。解决思路也简单，想办法让浏览器在跨域请求中支持带上cookie就可以了。

有两种处理方式：

• 方式一:

• Php服务端代码设置允许跨域cookie，并添加"Access-Control-Allow-Credentials"="true"
  以laravel框架为例，在中间件中添加以下代码:

public function handle($request, Closure $next)
{
   return $next($request)
       ->header("Access-Control-Allow-Credentials", "true")  //这里不能使用逻辑值true，只能使用字符串true
       ->header("Access-Control-Allow-Origin", $request->header("Origin"))
       ->header("Access-Control-Allow-Headers", $request->header("Access-Control-Request->Headers"))
       ->header("Access-Control-Request-Method", $request->header("Access-Control-Request->Method"));
}

设置的关键点是Access-Control-Allow-Credentials必须设置为true， 从而允许跨域请求时带上相关cookie。

• 客户端代码配置，
  以jQuery.ajax为例:

$.ajax({
   headers:{
       "Content-Type":"text/plain",
   },
   url:url,
   type:"POST",
   data: bodyText,
   dataType:"json",
   xhrFields: {
       withCredentials: true
   },
   beforeSend: function(xhr) {
       document.cookie = "XDEBUG_SESSION=PHPSTORM;domain=localhost;path=/";
   },
   async:false,
   // 允许跨域
   crossDomain: true,
   success:function(res){
   },
   error:function(err){
   },
   complete:function(res){
   },

})

设置的关键点是在xhrFields中增加withCredentials:true和在beforeSend函数中增加

document.cookie = "XDEBUG_SESSION=PHPSTORM;domain=localhost;path=/";

说明一点：跨域请求开启调试，通过chrome书签或者直接修改浏览器cookie的方式并不起作用，猜测原因可能是因为浏览器本身的cookie和XmlHttpRequest中的cookie并不是一回事儿。

• 方式二

• 借助nginx，开启跨域调试 (大招来啦！)
  现在大部分Phper开发的环境都是LNMP，那么我们可以请nginx帮忙修改cookie，从而将cookie传输到php服务端。
  nginx默认不支持修改请求的header字段，我们需要下载安装headers-more-nginx-module扩展，下载地址 https://github.com/openresty/headers-more-nginx-module。
  PS：给nginx安装扩展不再赘述了哦。不会的话，自己百度下吧。
• 修改nginx.conf虚拟主机配置，如下所示：

more_set_input_headers  "Cookie:XDEBUG_SESSION=PHPSTORM; $http_cookie";

其它操作同上，不再赘述。

3）php脚本调试

有两种处理方式：

• 方式一：
  打开Phpstorm，找到myscript.php文件，点击右键Debug 'myscript.php'即可。
• 方式二：
  修改环境变量也可以开启Xdebug调试

export XDEBUG_CONFIG="XDEBUG_SESSION=PHPSTORM"
php myscript.php

4）调试外网远程主机

分为如下几步：

• 设置内网穿透，用的是花生壳，我将花生壳分配的域名和端口指向我本机IP192.168.9.28和本机9001端口。

  
  
  

  内网穿透端口映射.png

PS：如果觉得内网穿透麻烦的话，也可以使用ssh来实现同样的功能，而且是免费的。
参见我写的另一篇文章利用ssh隧道，进行外网php xdebug调试和nodejs调试

• 修改远端主机php-fpm的php.ini的xdebug部分如下:

[Xdebug]
zend_extension="/usr/lib/php/20151012/xdebug.so"
xdebug.remote_enable=1
#mzxxxxxxxxxxxxxpc.cn就是内网穿透映射中提供的域名
xdebug.remote_host="mzxxxxxxxxxxxxxpc.cn"  
#4xxxx2就是内网穿透映射提供的端口
xdebug.remote_port=4xxxx2  
xdebug.remote_handler="dbgp"
xdebug.idekey=PHPSTORM

• 重启php-fpm

service php7.0-fpm restart

• openresty或者nginx的server块中添加以下配置，开启xdebug session。

more_set_input_headers  "Cookie:XDEBUG_SESSION=PHPSTORM; $http_cookie";

如果不愿意用openresty的方式，那么点击浏览器标签start-debugger也可开启xdebug session

• 本机IDE添加serverMapping映射

  
  
  

  serverMapping映射.png

• 新建一个运行调试php_webApplication的任务

  
  
  

  image

新建php web application.png

• 最后一步，打上断点，点击菜单上RUN=>debug xxx web Application，就可以开启调试了。

• 遗留问题：外网远程调试，必须点击菜单上的RUN=>debug xxx web Application才能正常进行调试，其它方式打开网站的话，调试总是会出各种各样的问题。

---

Xdebug开启调试的配置就这么简单。。。
END！

客官觉得写得好就打个赏呗^_^