Debugging PHP with VS Code, WSL 2 (Ubuntu 22.04), PHP 8.1 and Xdebug 3

Prerequisites

• Windows 11
• Visual Studio Code

Steps

Install WSL 2 and Ubuntu 22.04

wsl --install

Start Ubuntu

One of:

• Click Start > Ubuntu
• Open an Ubuntu tab in Windows Terminal

In Ubuntu

1. Add Ondřej Surý’s PPA:

   sudo add-apt-repository ppa:ondrej/php
   sudo apt update

2. Install Xdebug 3.2.0 for PHP 8.1 (this will also install PHP 8.1):

   sudo apt install -y php8.1-xdebug

3. Open /etc/php/8.1/cli/conf.d/20-xdebug.ini in an editor and paste the following configuration (the first line should already exist):

   zend_extension = xdebug.so
   xdebug.mode = develop,debug
   xdebug.discover_client_host = 1

4. Create a project folder:

   mkdir ~/demo
   cd ~/demo
   mkdir .vscode

5. Create a test file ~/demo/index.php with the following contents:

   <?php
    phpinfo();
   ?>

6. Start the PHP web server:

   php -S localhost:8080

In VS Code

1. Install the WSL extension like this:

   Press F1, press Backspace, paste the following command and press Enter:

   ext install ms-vscode-remote.remote-wsl

2. Install the PHP Debug extension like this:

   Press F1, press Backspace, paste the following command and press Enter:

   ext install xdebug.php-debug

3. Open the project folder in WSL like this:

   1. Press F1, enter WSL: Connect to WSL and press Enter
   2. Select the folder demo

4. Create the file ~/demo/.vscode/launch.json with the following contents:

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

5. Open the file index.php

6. Set a breakpoint on the second line

7. Press F5 to start debugging

In your web browser

1. Install “Xdebug helper” extension

   • Edge
   • Chrome
   • Firefox
   • Safari

2. Go to http://localhost:8080/

3. Click the extension’s icon and enable it

4. Reload the page

The breakpoint should now be hit.