From e3297cdcaed2b5ca84702bb76d2893bee8e07155 Mon Sep 17 00:00:00 2001
From: Sylvain Brunerie <sylvain.brunerie@gmail.com>
Date: Mon, 20 Oct 2025 11:44:58 +0200
Subject: [PATCH] Add "Setting up Xdebug" section in PHP docs (#40470)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page about PHP in the docs doesn’t explain how to use Xdebug. I had
a lof of trouble setting it up the first time, then recently had another
headache trying to get it to work again, because the value for `adapter`
had changed from `PHP` to `Xdebug`.

It’s likely that my example config isn’t perfect or has redundant stuff
or whatever, feel free to amend it.

I also took the liberty to set the Phpactor and Intelephense headings to
level 3 because I felt like they were part of "Choosing a language
server."

Release Notes:

- N/A
---
 docs/src/languages/php.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/docs/src/languages/php.md b/docs/src/languages/php.md
index 40c7f9a838e0435b952b25bb0072153ac2fcf4ec..b2b8dffcf1b973f769d2900c21385804fbb4394f 100644
--- a/docs/src/languages/php.md
+++ b/docs/src/languages/php.md
@@ -13,7 +13,7 @@ The PHP extension offers both `phpactor` and `intelephense` language server supp
 
 `phpactor` is enabled by default.
 
-## Phpactor
+### Phpactor
 
 The Zed PHP Extension can install `phpactor` automatically but requires `php` to be installed and available in your path:
 
@@ -25,7 +25,7 @@ The Zed PHP Extension can install `phpactor` automatically but requires `php` to
 which php
 ```
 
-## Intelephense
+### Intelephense
 
 [Intelephense](https://intelephense.com/) is a [proprietary](https://github.com/bmewburn/vscode-intelephense/blob/master/LICENSE.txt#L29) language server for PHP operating under a freemium model. Certain features require purchase of a [premium license](https://intelephense.com/).
 
@@ -60,3 +60,35 @@ To use the premium features, you can place your [licence.txt file](https://intel
 Zed supports syntax highlighting for PHPDoc comments.
 
 - Tree-sitter: [claytonrcarter/tree-sitter-phpdoc](https://github.com/claytonrcarter/tree-sitter-phpdoc)
+
+## Setting up Xdebug
+
+Zed’s PHP extension provides a debug adapter for PHP and Xdebug. The adapter name is `Xdebug`. Here a couple ways you can use it:
+
+```json
+[
+  {
+    "label": "PHP: Listen to Xdebug",
+    "adapter": "Xdebug",
+    "request": "launch",
+    "initialize_args": {
+      "port": 9003
+    }
+  },
+  {
+    "label": "PHP: Debug this test",
+    "adapter": "Xdebug",
+    "request": "launch",
+    "program": "vendor/bin/phpunit",
+    "args": ["--filter", "$ZED_SYMBOL"]
+  }
+]
+```
+
+In case you run into issues:
+
+- ensure that you have Xdebug installed for the version of PHP you’re running
+- ensure that Xdebug is configured to run in `debug` mode
+- ensure that Xdebug is actually starting a debugging session
+- check that the host and port matches between Xdebug and Zed
+- look at the diagnostics log by using the `xdebug_info()` function in the page you’re trying to debug