Quick Setup Guide for Remote SSH Debugging with VS Code and Xdebug 2

RemoteXdebug.md

Quick Setup Guide for Remote SSH Debugging with VS Code and Xdebug 2

Prerequisites

1. VS Code: Ensure you have Visual Studio Code installed.
2. Remote - SSH Extension: Install the Remote - SSH extension in VS Code.
3. PHP Debug Extension: Install the PHP Debug extension in VS Code.
4. Chrome Xdebug Helper Extension: Install the Xdebug Helper extension in Chrome.

Step-by-Step Setup

1. Configure Xdebug on Remote Server

First, find out which PHP ini file to modify by running the following script or command:

<?php
var_dump(php_ini_loaded_file(), php_ini_scanned_files());

Alternatively, you can run php --ini on the command line.

• If there is a file with xdebug in the name, such as /etc/php/7.4/cli/conf.d/99-xdebug.ini, then this is the file to use.
• If that file does not exist, but there are other files in a conf.d or similar directory, you can create a new file there. Please name it 99-xdebug.ini in that case.
• Otherwise, modify the php.ini file that is displayed through the script or php --ini command.

Add the following configuration to the appropriate file, or your php.ini file on the remote server:

; Note that we disable profiler and only enable the trigger.
; From your browser pass XDEBUG_PROFILE=1
; http://example.com/file.php?XDEBUG_PROFILE=1
[xdebug]
; For xdebug 2:
xdebug.profiler_enable_trigger=1
xdebug.profiler_enable=0

; VSCode remote debugging with Xdebug 2 when using SSH connection
xdebug.remote_log="/tmp/xdebug/log"
xdebug.remote_enable = 1
xdebug.remote_port = 9000
xdebug.remote_autostart = 0
xdebug.remote_host = 127.0.0.1

; For xdebug 3:
; xdebug.mode = debug
; xdebug.start_with_request = yes
; xdebug.client_port = 9000

Note

There could be more than one php.ini file. In many set-ups there is a different one for the command line (often cli/php.ini) and the web server (often fpm/php.ini).

Note

If you want to use Xdebug and OPCache together, you must have the zend_extension line for Xdebug below the line for OPCache, or in a file starting with a higher number (ie. 99-xdebug.ini vs 20-opcache.ini), otherwise they won't work properly together.

2. Set Up SSH Configuration

1. Open the SSH configuration file:

code ~/.ssh/config

2. Add the remote server configuration:

Host remote-server
    HostName your.remote.server.ip
    User your-username
    IdentityFile ~/.ssh/your-private-key

3. Connect to Remote Server in VS Code

1. Press F1 to open the command palette in VS Code.
2. Type Remote-SSH: Connect to Host... and select the remote server (remote-server).
3. VS Code will open a new window connected to the remote server.

4. Set Up VS Code Debug Configuration

1. In the remote VS Code window, go to the debug tab (Ctrl+Shift+D).
2. Click on the gear icon to open launch.json and add the following configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000
        }
    ]
}

5. Configure Xdebug Helper in Chrome

1. Open Chrome and click on the Xdebug Helper extension icon.
2. Click on the extension's settings (gear icon).
3. Set the IDE key to VSCODE.

6. Start Debugging in VS Code

1. In the VS Code debug tab, select Listen for Xdebug.
2. Click the green play button to start listening for Xdebug connections.
3. Use the Chrome Xdebug Helper extension to initiate debugging. Ensure it is set to Debug mode, then refresh the page you want to debug.

7. Verify and Debug

1. Place a breakpoint in your PHP code in VS Code.
2. Reload the page in Chrome.
3. The execution should pause at the breakpoint in VS Code, allowing you to debug your PHP code.

8. Troubleshooting

1. Log File: Check the Xdebug log file (/tmp/xdebug/log) for any errors.
2. Firewall: Ensure port 9000 is open on your remote server.
3. PHP Version: Make sure the installed Xdebug version is compatible with your PHP version.

That's it! You should now be able to debug PHP code running on a remote server using VS Code and Xdebug.