Frustrated Developer

How To Debug PHP Code On A Remote Server Using Xdebug and VS Code Via VPN

Posted on Posted in Debugging, PHP Development

The Problem

Updating to a new version of any Content Management System (CMS) can lead to many errors in your website, especially when using custom plugins, modules or components. When these errors arise you will need to have some sort of strategic approach to resolving your bugs. Bugs are never pleasant but we can learn so much from them and they certainly help to shape the type of developer we become. In the past I have faced challenges when debugging code that resides on a remote server, that in order to connect, requires a connection to a virtual private network (VPN). One challenge that I have faced is finding a way to debug that remote code in my local development environment with apache and PHP running on a remote server. In this tutorial, I will show you how to overcame that challenge.


In order to debug my PHP code I used xdebug.

Xdebug is an extension for PHP to assist with debugging and development. It contains a single step debugger to use with IDEs; it upgrades PHP’s var_dump() function; it adds stack traces for Notices, Warnings, Errors and Exceptions; it features functionality for recording every function call and variable assignment to disk; it contains a profiler; and it provides code coverage functionality for use with PHPUnitXdebug

The remote server was running Linux within a VPN. hence I had no way of connecting directly to server without first connecting to the VPN. My development computer runs on Windows 10 and I use Visual Studio Code as my IDE.


For this tutorial we are using version 7.2 of PHP on our remote server. Xdebug recommends that you have PHP version 7.X which is needed to work with latest version of their debugger. However you can visit their archive and download the version of xdebug that corresponds to your version of PHP. In order for the debug process to work, xdebug requires a client running on the development environment. Since I am using Visual Studio Code, I will be using the PHP Debug extension. Please see a list of all software used below:

Remote Server (CentOS 6):

Development Computer(Windows 10):

Remote Server Configuration

  • We will start off by installing Xdebug on the remote server. Log into your remote server and type the following command:
  • Unpack tar archive
tar -xf xdebug-2.6.0.tgz
  • Change directory to unpacked directory
cd xdebug-2.6.0
  • Run phpize
  • If phpize is unavailable for you. You can install it by installing php-devel package. On centos run:
sudo yum install php-devel
  • Compile and install xdebug. If not already installed, you will also need gcc in order to compile.
./configure --enable-xdebug
make install

For other installation methods please visit 

  • Now that we have installed xdebug, we need to enable the extension in php as a zend extension. Add the following line to your php.ini file to enable xdebug:
zend_extension =
  • You will also need to configure xdebug to work with PHP Debug; Please also add the following lines to your php.ini file:
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_log = /var/log/xdebug.log ; Logs xdebug outputs to a file. This is very useful for troubleshooting.
xdebug.remote_port= 9000 ; Port that development computer listens on.
xdebug.remote_host = ; IP address of your development computer.
  • Create a text phpinfo page to see if xdebug was installed properly. If it was installed properly xdebug version will appear under zend engine details, see below:

Zend Engine with xDebug

SSH Tunneling

PHP Debug’s documentation will tell you that xdebug.remote_host should be set to your IP or setting xdebug.remote_connect_back = 1 in order to enable remote host debugging. My case was different since I was connecting to the remote server using a VPN. To create a direct connection to my computer and the remote server so that Xdebug could talk to PHP Debug Client, a reverse SSH tunnel was used, where the remote port 9000 was forwarded to my local port 9000. This means that all data that is sent through port 9000 on the remote server, is received on my local port 9000. I used port 9000 because this is the default port that xdebug uses but the port number can be any of your free ports.
  • To enable port forwarding in OpenSSH, change the following line in your sshd_config file:
    • Change GatewayPorts no to GatewayPorts yes. If the line is commented, make sure to uncomment.
GatewayPorts yes
  • Lastly, restart apache and ssh on the remote server.
sudo service httpd restart
sudo service sshd restart
You have now completed the steps needed for the remote server. Now we will move on to the development computer.

Development Environment

  • Let us first start with creating SSH Tunnel between the remote server and the development environment. To do open your favorite SSH client and enter the following command:
ssh -R 9000: username@server-ip

VSCode PHP Debug

  • Now you need to open your project folder and configure PHP Debug. Your project folder should be a local copy of your code from the remote server.
    1. Click on the debug icon on the right side of VS Code.
    2. Click the gear icon that appears beside “No configuration”.
    3. Select PHP.

VS Code PHP Debug Config

  • Add the following to your launch.json script:
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9000,
        "log": true,
        "pathMappings": {
           "/test": "${workspaceFolder}"
  • You should modify “pathMappings” according to your project path on your remote server and your local copy.
VS Code PHP Debug Config
  • Open a script from you project folder and add a breakpoint.
VS Code - PHP Debug - Breakpoint
  • Start debugger and run remote server script from your browser.

VS Code PHP Debug - Start Debugger

Browser - XDebug

  • At this point if all went well, your script should stop at the breakpoint that you defined earlier. Go back to VS Code to inspect. You should now be able to step through your code and see if your script is working as intended. A list of your variables should be available for you to traverse.

VS Code - PHP Debug - Breakpoint Stop


Possible Errors And Solutions

  1. If apache error_log shows that xdebug is unable to open/write to log file(” Xdebug could not open the remote debug file”). Log into your remote server and fix using the following steps:
    • Create log file:
      touch /path-to-file/xdebug.log
    • Make apache the owner. Please note apache username varies depending on your Linux distribution:
      sudo chown apache:apache /path-to-file/xdebug.log
    • Give 644 permission:
      sudo chmod 644 /path-to-file/xdebug.log


  2. SSH Tunneling gives the following error, “Warning: remote port forwarding failed for listen port 9000”. Another application might be using port 9000. Fix using the following steps:
    • Check process id of processes using port 9000:
      lsof|grep 9000
    • Kill process and try ssh tunneling again:
      sudo kill <pid>
    • If you have an important application running that you do not want to kill you can consider using another port number. Simply replace port number in php.ini with your favored port and adjust ssh tunneling command accordingly.

I hope that you found this tutorial informative and helpful. If you have any issues following these steps or need help with something else, drop a comment below. If you enjoyed, please consider sharing. Happy coding!

Please follow and like us:

Leave a Reply

Your email address will not be published. Required fields are marked *