PHP Remote Debugging

R3zk0n · October 2, 2025

API   Linux   Windows
Contents
    1. Make sure that XDebug is installed on the remote server (https://xdebug.org/docs/install) Installing it can be a bit finicky, so try and install it with PECL if you are on Linux.
    $ pecl install xdebug

    On Windows, downloading and compiling the Source is the best way. Make sure the version of XDebug you are downloading is compatible with the version of PHP you are running.

    1. On the remote server, add the following code to the bottom of your php.ini file:

    Code: [XDebug] ;; Only Zend OR (!) XDebug zend_extension=/path/to/xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.discover_client_host=true xdebug.client_host=localhost xdebug.client_port=9001 xdebug.log=/tmp/xdebug.log xdebug.log_level=7 xdebug.connect_timeout_ms=1000 You can use the following commands to see if XDebug is loaded and where the php.ini files are located:

    php -v
php --ini

    1. Restart PHP and Apache (or whatever web server you are running) on the remote server.

    2. Create a new mount point directory on your machine for the remote directory:

    $ sudo mkdir /mnt/debug
    1. Remote mount the directory of the remote application (or directory that contains the files and sub-folders of for the application) on your machine (to avoid having to copy all of the remote files to your machine):
    $ sudo sshfs -o allow_other,default_permissions user@machine:/path/to/program /mnt/debug
    1. Use SSH remote port forwarding to get access to the XDebug port:
    $ ssh -fNR 9001:localhost:9001 user@machine
    1. Open the mounted folder with Visual Studio code:
    $ cd /mnt/debug
$ code .
    1. Install the PHP Debug extension for Visual Studio code and create a “Listen for Xdebug” launch.json file configuration: Example:

    Code: { // Use IntelliSense to learn about possible attributes. // Hover to view descriptions of existing attributes. // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 “version”: “0.2.0”, “configurations”: [ { “name”: “Listen for Xdebug”, “type”: “php”, “request”: “launch”, “port”: 9001, “pathMappings”: { “/path/to/remote/application/folder”: “${workspaceFolder}”, }, } ] }

    1. Start the debugger and set breakpoints to start debugging. Note After walking through a breakpoint and stepping out of it, you may have to stop and restart the debugger to set a new one.

    2. When finished debugging, unmount the directory mount created in step 5:

    $ sudo umount /mnt/debug

    Edit: If you run into an issue where you can’t write to files in the the remote mounted directory, try removing the ‘default_permissions’ flag when running SSHFS:

    Code: $ sshfs -o allow_other user@machine:/path/to/program /mnt/debug

    Twitter, Facebook