diff --git a/docs/src/languages/php.md b/docs/src/languages/php.md
index 40c7f9a838e043..b2b8dffcf1b973 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