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.

PHP in Docker

Updated: 17 May 2024

Pre-configured Docker images (including Xdebug) from Jetbrains https://github.com/JetBrains/phpstorm-docker-images


Run a php script

docker run -it --rm --name my-running-script \
-v "$PWD":/usr/src/myapp \
-w /usr/src/myapp \
php:7.4-cli php script.php

Run the php development server

docker run -it --rm --name php-server \
-v "$PWD":/usr/src/myapp \
-w /usr/src/myapp \
-p 8000:8000 \
php:8.2-cli php -S 0.0.0.0:8000

Homestead Vagrant xdebug3 vscode phpspec

Updated: 18 July 2021

Reset to original state

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

.vscode/launch.json

{
    "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

zend_extension=xdebug.so
xdebug.mode = debug
xdebug.discover_client_host = true
xdebug.client_host = 192.168.10.1
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

php74

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

xon

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 192.168.10.10:80 -host-header=site.dev