Remote Linux server PHP debugging using PhpStorm Xdebug with its port forwarded through SSH tunnel

If your client's site setup is complicated and you don't have time to replicate it in your local machine, your choice is to debug it directly. This article will show steps on how to debug a website's PHP codes remotely in a server with firewall specifically hosted in Linode server running Centos 7 64-bit Linux distribution, PHP-FPM (FastCGI Process Manager) and PHP 7.0 (the server is running multiple PHP versions).

Steps (remote server):

  1. Install Xdebug in your server:

      
    scl enable rh-php70 bash
    pecl install Xdebug
      
    

    Edit:

      
    vi /etc/opt/rh/rh-php70/php.d/15-xdebug.ini
      
    

    Have the following as its content to enable Xdebug:

      
    ; Enable xdebug extension module
    zend_extension=xdebug.so
      
    
  2. Xdebug will need a port (usually its port 9000). To make sure the port that we will use for Xdebug is available, lets check which ports are in use:

      
    netstat -lntu
      
    

    ... or:

      
    ss -lntu
      
    

    It will display something like this:

      
    Active Internet connections (only servers)
    Proto Recv-Q Send-Q Local Address           Foreign Address         State
    tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN
    tcp        0      0 127.0.0.1:9000          0.0.0.0:*               LISTEN
    tcp        0      0 127.0.0.1:80            0.0.0.0:*               LISTEN
      
    

    Since port 9000 is already used (by PHP-FPM pool), we will use port 9001 for our Xdebug.

  3. Edit a pool you wish Xdebug will run:

      
    vi /etc/opt/rh/rh-php70/php-fpm.d/www.conf
      
    

    Append the following:

      
    ; XDebug
    php_value[xdebug.default_enable] = 1
    php_value[xdebug.remote_enable] = 1
    php_value[xdebug.remote_port] = 9001
    php_value[xdebug.idekey] = WEBFOOBAR
    php_value[xdebug.max_nesting_level] = 256
    php_value[xdebug.remote_host] = 127.0.0.1
    php_value[xdebug.remote_log] = /var/opt/rh/rh-php70/log/php-fpm/xdebug.log
      
    
  4. Restart the PHP-FPM service:

      
    systemctl restart rh-php70-php-fpm
      
    

    Xdebug information should show in your phpinfo():

    PHP info for Xdebug

  5. Make sure that Allow TCP forwarding is enabled in your SSH server settings:

      
    vi /etc/ssh/sshd_config
      
    

    Look for:

      
    AllowTcpForwarding yes
      
    

    Restart the SSH service:

      
    systemctl restart sshd
      
    

Steps (local machine):

  1. Our site's remote server is protected with firewall and it will prevent the Xdebug from connecting to PhpStorm. We will use SSH tunnel port forwarding as a solution. If your local machine has ssh client command line program, execute the following command:

      
    ssh -i ~/.ssh/id_rsa -R 9001:127.0.0.1:9000 user@srv.webfoobar.com
      
    

    Where:
    -i ~/.ssh/id_rsa include this ssh option if your server SSH is using Key-Based Authentication
    -R 9001:127.0.0.1:9000 opens up port 9001 as we set the server's Xdebug's xdebug.remote_port to 9001 earlier then forwarded to 127.0.0.1:9000 where PhpStorm is listening
    user@srv.webfoobar.com are the username and hostname of the server

    Note: If you want to change the Xdebug listening port of PhpStorm, click "File" > "Settings..." > "Languages & Frameworks" > "PHP" > "Debug". Under "Xdebug" change the "Debug port" to your desired port.

    PhpStorm change Xdebug listening port

  2. If you are using Windows, download PuTTY here to use as SSH client and this client has setting for SSH tunnel port forwarding also.

    Configure first your normal session and go to "Connection" > "SSH" > "Tunnels" of the PuTTY settings and populate the "Source port" with 9001 and "Destination" with 127.0.0.1:9000; select "Remote" option; click "Add" button:

    PuTTY SSH tunnel settings

    And don't forget to go back to the "Session" tab and click "Save" button to save this settings. Finally, click "Open" button to start your SSH session to your site's server.

  3. Now, to test if the SSH tunnel port forwarding works, run the following command inside your SSH prompt:

      
    netstat -a -n | grep 9001
      
    

    You should see something like this as response:

      
    tcp        0      0 127.0.0.1:9001          0.0.0.0:*               LISTEN
      
    
  4. Follow the steps in this article to create a PhpStorm project from a remote host.

  5. In your PhpStorm, click "Run" > "Break at first line in PHP scripts". This is optional, it is just to ensure that the PhpStorm will trigger when we started to debug our site. To start the PhpStorm listening to Xdebug, click "Run" > "Start Listening for PHP Debug Connections":

    PhpStorm Start Listening PHP debug

  6. Open your favorite web browser and visit your site. This should pop a window at PhpStorm that there's incoming connection from Xdebug, just click the "Accept" button:

    Xdebug incoming connection

    Your PhpStorm will trigger to stop and highlight at the first line in your site's PHP script:

    Xdebug break at first PHP line

Add new comment

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.