diff --git a/README.md b/README.md
index 9ea76c1..f2b1a76 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,7 @@ For a tutorial and usage overview, take a look at the
       * [TCL](#tcl)
       * [C♯](#c)
       * [Go](#go)
+      * [PHP](#php)
       * [JavaScript, TypeScript, etc.](#javascript-typescript-etc)
       * [Java - partially supported](#java---partially-supported)
    * [FAQ](#faq)
@@ -760,6 +761,79 @@ Requires:
 }
 ```
 
+## PHP
+
+This uses the php-debug, see
+https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug
+
+Requires:
+
+* (optional) Xdebug helper for chrome https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc
+* `install_gadget.py --force-enable-php`
+* configured php xdebug extension 
+```ini
+zend_extension=xdebug.so
+xdebug.remote_enable=on
+xdebug.remote_handler=dbgp
+xdebug.remote_host=localhost
+xdebug.remote_port=9000
+```
+replace `localhost` with the ip of your workstation.
+
+lazy alternative
+```ini
+zend_extension=xdebug.so
+xdebug.remote_enable=on
+xdebug.remote_handler=dbgp
+xdebug.remote_connect_back=true
+xdebug.remote_port=9000
+```
+
+* .vimspectory.json
+```json
+{
+  "configurations": {
+    "Listen for XDebug": {
+      "adapter": "vscode-php-debug",
+      "configuration": {
+        "name": "Listen for XDebug",
+        "type": "php",
+        "request": "launch",
+        "port": 9000,
+        "stopOnEntry": false,
+        "pathMappings": {
+          "/var/www/html": "${workspaceRoot}"
+        }
+      }
+    },
+    "Launch currently open script": {
+      "adapter": "vscode-php-debug",
+      "configuration": {
+        "name": "Launch currently open script",
+        "type": "php",
+        "request": "launch",
+        "program": "${file}",
+        "cwd": "${fileDirname}",
+        "port": 9000
+      }
+    }
+  }
+}
+```
+
+### Debug web application
+append `XDEBUG_SESSION_START=xdebug` to your query string
+```
+curl "http://localhost?XDEBUG_SESSION_START=xdebug"
+```
+or use the previously mentioned Xdebug Helper extension (which sets a `XDEBUG_SESSION` cookie)
+
+### Debug cli application
+```
+export XDEBUG_CONFIG="idekey=xdebug"
+php <path to script>
+```
+
 ## JavaScript, TypeScript, etc.
 
 * Node.js
diff --git a/install_gadget.py b/install_gadget.py
index 9b6f56f..ef4b46a 100755
--- a/install_gadget.py
+++ b/install_gadget.py
@@ -291,6 +291,29 @@ GADGETS = {
       },
     },
   },
+  'vscode-php-debug': {
+    'language': 'php',
+    'enabled': False,
+    'download': {
+      'url': 'https://github.com/felixfbecker/vscode-php-debug/releases/download/'
+             '${version}/${file_name}',
+    },
+    'all': {
+      'version': 'v1.13.0',
+      'file_name': 'php-debug.vsix',
+      'checksum':
+        '8a51e593458fd14623c1c89ebab87347b087d67087717f18bcf77bb788052718',
+    },
+    'adapters': {
+      'vscode-php-debug': {
+        'name': "php-debug",
+        'command': [
+          'node',
+          "${gadgetDir}/vscode-php-debug/out/phpDebug.js",
+        ]
+      }
+    }
+  },
   'vscode-node-debug2': {
     'language': 'node',
     'enabled': False,