How to configure PHP, Xdebug, Docker and PHPStorm

Updated: 15 November 2023

1. Select these two items in PHPStorm:
Run > Start Listening for PHP Debug Connections
Run > Break at first line in PHP scripts

2. Load a page in a web browser.

3. PHPStorm should display an Incoming Connection From Xdebug dialog box.

4. From the bottom of the dialog, select the local file which matches the ‘File path on server’ value and click Accept.

Homestead Vagrant xdebug3 vscode phpspec

Updated: 18 July 2021

Reset to original state

./vagrant destroy --force && ./vagrant up


    "version": "0.2.0",
    "configurations": [
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "log": true,
            "pathMappings": {
                "/home/vagrant/homestead.test": "/home/chris/code/homestead.test"

Start an ssh session

./vagrant ssh

Create the xdebug log file

sudo touch /var/log/xdebug.log && sudo chmod 777 /var/log/xdebug.log

Create xdebug settings
sudo nano /etc/php/7.4/fpm/conf.d/20-xdebug.ini
xdebug.mode = debug
xdebug.discover_client_host = true
xdebug.client_host =
xdebug.client_port = 9003
xdebug.max_nesting_level = 512

; required for cli debugging but for browser
; could omit and use query string at end
; of url instead XDEBUG_SESSION_START=name
xdebug.start_with_request = yes

; ensure file exists and is writeable
xdebug.log = /var/log/xdebug.log

Switch to cli PHP 7.4


For cli debugging (alias xon=’sudo phpenmod -s cli xdebug’)


After these changes

./vagrant reload --provision

Run phpspec

./vagrant ssh
tail -f /var/log/xdebug.log
project/dir vendor/bin/phpspec run

If vscode will not stop on a breakpoint try re-enabling PHP Debug extension and restarting vscode.

Run ngrok (outside of Homestead) pointing at a configured Homestead site

ngrok http