How to Debug Any Console PHP Script with XDebug in 2025

Sometimes you need to to debug a console script. Normally, it is as simple as this:
For XDebug 3:

php -dxdebug.mode=debug -dxdebug.client_host=192.168.1.100 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes path/to/script/myscript.php

For XDebug 2:

php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host=192.168.1.100 -dxdebug.remote_connect_back=0 path/to/script/myscript.php

Replace:

• 192.168.1.100 with the IP address of the machine where your IDE is running — for example, PhpStorm
• path/to/script/myscript.php with the path to the script you’re debugging

(source)

But there are cases when calling a console command with parameters is inconvenient. For example:

1. You need to debug a Codeception or PHPUnit test that you run from the terminal.
For example, you’re running an integration test in Codeception and want to quickly debug it without adding those parameters every time:

php vendor/bin/codecept run Integration tests/Integration/MyIntegrationTest.php --debug

2. Or you’re using curl in the terminal to connect to a development HTTP server:

 curl -I http://www.wpd98.com/gutenberg-color-palette/

In these situations, you can easily enable debugging for your console scripts like this:

1. Change the XDebug configuration.
On Ubuntu 22.04 you’ll need to modify the file /etc/php/8.1/conf.d/20-xdebug.ini:

zend_extension=xdebug.so
xdebug.mode=debug
# the default port for XDebug 3 is 9003, for XDebug 2 it was 9000
xdebug.client_port=9003
xdebug.client_host=192.168.1.100
xdebug.start_with_request=yes

, where 192.168.1.100 is the IP address of your host machine running PhpStorm (or any IDE of your choice).

The line

xdebug.start_with_request=yes

tells Xdebug to automatically start a debugging session on any request — whether you’re making a request to a PHP script over HTTP or running a PHP script from the command line.

If you’re using PHP as an Apache module, and you’re debugging a PHP script over HTTP — for example, calling the script with curl from the terminal — restart Apache after making the changes. On Ubuntu, use:

service apache2 restart

2. If you’re on a virtual machine and making requests with curl to a test HTTP server — for example, www.wd98.com — make sure your VM recognizes the domain:
Add to /etc/hosts:

127.0.0.1 www.wd98.com

3. Enable debugging in PhpStorm (or any IDE of your choice) and set a breakpoint.

Now, when you run any console PHP script in the terminal, it will stop at your breakpoint.

Conclusion

Thanks for reading to the end.

I would greatly appreciate any thoughts or comments. It would be very kind of you to leave them below.