VSCode+Xdebug+PHPStudy

## 参考
> https://blog.csdn.net/weixin_43743720/article/details/141086179
> https://blog.csdn.net/llainannan/article/details/135141122
> https://zhuanlan.zhihu.com/p/113171737

## 安装

### VSCode

- 下载安装 VSCode 完成后，安装扩展如下
  1. Chinese (Simplified) (简体中文) Language Pack for Visual Studio Code
    - VSCode 中文翻译扩展
  2. PHP Intelephense
    - 使用扩展，自动写代码时完成一些补充之类的
  3. PHP Debug
    - 使用Xdebug调试PHP

### PHP Debug 及 Xdebug 配置

#### Xdebug 安装及 PHP扩展配置

- PHP Debug是Derick Rethans编写的在VSCode和Xdebug之间的调试器。**Xdebug是需要安装在PHP运行服务器上的PHP扩展**（Linux上为.so文件，Windows上为.dll）。
- 安装Xdebug前先在服务器根目录下创建一个test.php文件，内容如下：

```php
<?
    php phpinfo(); 
?>
```
- 这个代码可以打印 PHP 的环境信息。然后配置 PHP 环境中的 Xdebug：
- 下载 Xdebug：
  - 在Windows上：下载适用于环境的**PHP版本、体系结构（64/32位）、线程安全（TS/NTS）和Visual Studio编译器版本**的预编译DLL，**并将其放置在您的PHP扩展文件夹中**。
  - 在Linux上：要么下载tarball格式的源代码，要么用git克隆，然后编译它。或者看看官网上是否提供了编译完成的软件包。
  - 下载地址：https://xdebug.org/download 。历史版本：https://xdebug.org/download/historical
  - 如果不知道当前php的版本,又懒得去找那么就试试这个地址:https://xdebug.org/wizard ,这个是xdebug官方网站给用户提供的一个自动分析当前电脑系统对应的xdebug版本的页面。将phpinfo的内容全部复制进去即可有推荐下载的 xdebug 文件。

- 我搭建测试环境使用的 PHPStudy，里面的PHP版本都是NTS，在软件内点击【网站】->【管理】->【php扩展】中能看到xdebug。没有勾选的时候就可以在phpstudy目录的php扩展文件夹下找到xdebug，勾选上等于帮我们自动完成了后续的几步操作。其在php.ini中最下面**自动添加**的内容如下：
- 这里的版本是 2.7.2

```
[Xdebug]
zend_extension=C:/phpstudy_pro/Extensions/php/php7.3.4nts/ext/php_xdebug.dll
xdebug.collect_params=On
xdebug.collect_return=1
xdebug.auto_trace=Off
xdebug.trace_output_dir=C:/phpstudy_pro/Extensions/php_log/php7.3.4nts.xdebug.trace
xdebug.profiler_enable=Off
xdebug.profiler_output_dir=C:/phpstudy_pro/Extensions/php_log/php7.3.4nts.xdebug.profiler
xdebug.remote_enable=Off
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
```

- 修改上面的php.ini的部分内容 `xdebug.remote_enable=Off` 改为如下
```
xdebug.remote_enable=On
xdebug.remote_autostart =On
```
- 然后重启下 PHPStudy 的WNMP。

如果不是 phpstudy，则按照如下配置：
- 通过在PHP服务器上的环境配置(PHP.ini)中添加 zend_extension=Xdebug的路径 来使用Xdebug。php.ini的路径显示在访问test.php中的“Loaded Configuration File”配置下显示。

- 在php.ini中启用远程调试：
- 对于Xdebug v3.x.x：

```
xdebug.mode = debug
xdebug.start_with_request = yes
```

- 对于Xdebug v2.x.x:

```
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_port = 9000
```

- （可看可不看）还有其他方法可以告诉Xdebug连接到远程调试器，如Cookie、查询参数或浏览器扩展。我推荐 remote_autostart（Xdebug v2）/start_with_request（Xdebugv3），因为它“刚刚工作”。还有其他各种选项，如端口，请参阅远程调试的Xdebug文档以获取更多信息。请注意，**默认的Xdebug端口从Xdebug v2到v3从9000更改为9003。**(翻译的不好，原文如下：*There are other ways to tell Xdebug to connect to a remote debugger, like cookies, query parameters or browser extensions. I recommend remote_autostart (Xdebug v2)/start_with_request (Xdebug v3) because it "just works". There are also a variety of other options, like the port, please see the Xdebug documentation on remote debugging for more information. Please note that the default Xdebug port changed between Xdebug v2 to v3 from 9000 to 9003.*)

- 通过检查phpinfo()输出中是否有 Xdebug 来验证安装是否成功。

#### VSCode配置

##### 具体操作
- 点击文件->首选项->设置 出现以下弹框，输入php进行搜索，点击结果中的PHP Debug，点击在 setting.json 中编辑。
- 编辑 setting.json ，主要配置下`php.validate.executablePath`和`php.debug.executablePath`，配置为你本地 php 目录，以下是完整内容：

> 请注意端口，要与后面的 php.ini 中的端口相同，例如在该配置中 port 为9000，php.ini 中设置也要为9000

```
{
    "php.debug.executablePath": "C:\\phpstudy_pro\\Extensions\\php\\php7.3.4nts\\php.exe",
    "php.validate.executablePath":"C:\\phpstudy_pro\\Extensions\\php\\php7.3.4nts\\php.exe"
}
```

- 然后点击调试，【创建 launch.json 文件】，将里面所有的 `port` 后面的端口，**改成 php.ini 中设置的端口**。

- 然后将 launch.json文件全部复制，打开前面的 setting.json，修改setting.json文件如下：

```
{
    "php.debug.executablePath": "C:\\phpstudy_pro\\Extensions\\php\\php7.3.4nts\\php.exe",
    "php.validate.executablePath":"C:\\phpstudy_pro\\Extensions\\php\\php7.3.4nts\\php.exe",
    "launch": // 将launch.json 文件的内容复制到这里即可。
}
```
- 记住将 launch.json 的内容复制进去。
- 然后随便编写一段代码：

```php
<?php
$a = 1;
echo $a;
$b =2;
echo $b;
$c = 3;
echo $c;
?>
```
- 开始调试，`如果调试的时候没有看到箭头和变量监控，将 Listen for Xdebug 改成 Launch currently open script`即可

##### 参考资料（来自PHP Debug的官方说明）
- 在您的项目中，转到调试器，点击小齿轮图标并选择PHP。将为您创建一个新的启动配置，其中包含三种配置：

1. 监听 Xdebug：此设置将简单地开始在指定端口（**默认情况下为 9003**）上监听 Xdebug。如果您按照推荐的方式配置了 Xdebug，每当您通过浏览器向 Web 服务器发出请求或启动 CLI 脚本时，Xdebug 将连接，您可以在断点、异常等处停止。
2. 启动当前打开的脚本：此设置是 CLI 调试的示例。它将以 CLI 方式启动当前打开的脚本，并在调试控制台中显示所有 stdout/stderr 输出，脚本退出后结束调试会话。
3. 启动内置 web 服务器：此配置将在随机端口上启动 PHP 内置 Web 服务器，并使用 serverReadyAction 指令打开浏览器。端口是随机的（localhost:0），但可以更改为所需的固定端口（例如：localhost:8080）。如果需要路由脚本，可以通过 program 指令添加。其他 PHP/Xdebug 指令将在每次页面加载时触发调试。

- 还有用于 Xdebug v2（旧版）安装的配置选项。

- 有关使用 VS Code 进行调试的更多一般信息，请访问 https://code.visualstudio.com/docs/editor/debugging。

- 注意：您甚至可以在没有 launch.json 的情况下调试脚本。如果没有打开文件夹，并且 VS Code 状态栏为紫色，按 F5 将使用 Xdebug3 特定参数启动打开的脚本。如果 php 可执行文件不在路径中，您可以通过设置 php.debug.executablePath 提供它。为了使调试正常工作，Xdebug 仍然必须正确安装。

- 支持的 launch.json 设置：
  - request：始终为 "launch"。
  - hostname：监听 Xdebug 时绑定的地址（默认：如果可用，则为所有 IPv6 连接，否则为所有 IPv4 连接）或 Unix 域套接字（以 unix:// 为前缀）或 Windows 管道（\?\pipe\name） - 不能与端口组合使用。
  - port：监听 Xdebug 的端口（默认：9003）。如果将端口设置为 0，系统将选择一个随机端口，并且 ${port} 占位符将在 env 和 runtimeArgs 中替换为所选端口。
  - stopOnEntry：是否在脚本开始时中断（默认：false）。
  - pathMappings：服务器路径与您机器上本地源路径的映射列表，见下文的“远程主机调试”。
  - log：是否记录 VS Code 与适配器之间的所有通信到调试控制台。有关故障排除的信息请参见下文。
  - ignore：一个可选的 glob 模式数组，指定要忽略的错误（例如 /vendor//*.php）。
  - ignoreExceptions：一个可选的异常类名数组，指定要忽略的异常（例如 BaseException, \NS1\Exception, *\Exception 或 *\Exception）。
  - skipFiles：一个 glob 模式数组，在调试时跳过这些文件。允许使用星号模式和否定，例如 /vendor/ 或 !/vendor/my-module/。
  - skipEntryPaths：一个 glob 模式数组，如果入口脚本匹配则立即分离并忽略调试（例如 **/ajax.php）。
  - maxConnections：仅接受此数量的并行调试会话。额外的连接将被丢弃，其执行将继续而不进行调试。
  - proxy：DBGp 代理设置。
    - enable：要启用代理注册，请设置为 true（默认值为 false）。
    - host：代理的地址。支持主机名、IP 地址或 Unix 域套接字（默认：127.0.0.1）。
    - port：适配器将注册到代理的端口（默认：9001）。
    - key：一个唯一的密钥，允许代理将请求与您的编辑器匹配（默认：vsc）。默认值来自 VSCode 设置中的 php.debug.idekey。
    - timeout：在放弃与代理的连接之前等待的毫秒数（默认：3000）。
    - allowMultipleSessions：代理是否应该同时转发多个会话/连接（默认：true）。
  - xdebugSettings：允许您覆盖 Xdebug 的远程调试设置，以更好地调整 Xdebug 以满足您的需求。例如，您可以调整 max_children 和 max_depth，以改变初始检索的数组和对象子项的最大数量，以及在数组和对象等结构中的最大深度。这可以加快在慢速机器上的调试器速度。有关可以设置的功能名称的完整列表，请参考 Xdebug 文档。
    - max_children：初始检索的数组或对象子项的最大数量。
    - max_data：初始检索的变量数据的最大量。
    - max_depth：调试引擎在向 IDE 发送数组、哈希或对象结构时可能返回的最大深度（通常无需更改，因为深度是逐步检索的，较大的值可能导致 IDE 挂起）。
    - show_hidden：此特性可以由 IDE 设置，以便它希望获取更详细的内部信息（例如类的私有成员等）。零表示隐藏成员不会显示给 IDE。
  - xdebugCloudToken：不是在本地监听，而是打开连接并与 Xdebug Cloud 注册，并在该连接上接受调试会话。

- 与 CLI 调试相关的特定选项：
  - program：应启动的脚本的路径。
  - args：传递给脚本的参数。
  - cwd：启动脚本时使用的当前工作目录。
  - runtimeExecutable：用于启动脚本的 PHP 二进制文件的路径。默认使用 PATH 中的文件。
  - runtimeArgs：传递给 PHP 二进制文件的额外参数。
  - externalConsole：在外部控制台窗口中启动脚本，而不是在调试控制台中（默认值：false）。
  - env：传递给脚本的环境变量。
  - envFile：可选的路径，指向包含环境变量定义的文件。

- 特性
  - 行断点
  - 条件断点
  - 命中计数断点：支持条件，如 >=n、==n 和 %n。
  - 函数断点
  - 步过、步入、步出
  - 在入口处中断
  - 从停止于入口开始 (F10/F11)
  - 在未捕获异常和错误/警告/通知时中断
  - 多个并行请求
  - 堆栈跟踪、作用域变量、超级全局变量、自定义常量
  - 数组和对象（包括类名、私有和静态属性）
  - 调试控制台
  - 监视
  - 设置变量
  - 作为 CLI 运行
  - 无调试运行
  - DBGp 代理注册和注销支持
  - Xdebug Cloud 支持

- 远程主机调试
  - 要调试在远程主机上运行的应用程序，您需要告诉 Xdebug 连接到不同于 localhost 的 IP。这可以通过将 `xdebug.client_host` 设置为您的 IP 来完成，或通过将 `xdebug.discover_client_host` 设置为 1，使 Xdebug 始终连接回发出 Web 请求的机器。后者是唯一支持多个用户调试同一服务器并且“自动工作”于 Web 项目的设置。有关该主题的更多信息，请参见 Xdebug 文档。

- 为了使 VS Code 将服务器上的文件映射到您本地计算机上的正确文件，您必须在 launch.json 中设置 pathMappings 设置。例如：

```json
// 服务器 -> 本地
"pathMappings": {
  "/var/www/html": "${workspaceFolder}/www",
  "/app": "${workspaceFolder}/app"
}
```

- 请注意，设置任何 CLI 调试选项将无法与远程主机调试一起使用，因为脚本始终是在本地启动的。如果您想在远程主机上调试 CLI 脚本，需要从命令行手动启动它。

- 代理支持
  - 调试器可以使用 IDE 密钥向 DBGp 代理注册自己。代理将仅转发具有该指定 IDE 密钥的 DBGp 会话到 IDE。这在多用户环境中非常有用，因为开发人员无法同时使用相同的 DBGp 端口。需要仔细设置，以便对 Web 服务器的请求包含匹配的 IDE 密钥。

- 官方的 dbgpProxy 实现。

- 此外，强烈建议使用 Xdebug 辅助浏览器扩展。在那里，可以轻松配置请求侧的 IDE 密钥。

- 故障排除
  - 在 StackOverflow 上提问。
  - 如果您认为发现了 bug，请打开一个 issue。
  - 确保您安装了此扩展和 Xdebug 的最新版本。
  - 尝试使用简单的 PHP 文件重现问题，例如来自测试项目的文件。
  - 在您的 launch.json 中设置 "log": true，并观察调试控制台面板。
  - 在您的 php.ini 中设置 xdebug.log = /path/to/logfile（确保您的 Web 服务器对该文件具有写入权限）。
  - 在 Twitter 上联系 @damjancvetko。