Setting Up Xdebug with VSCodium on Linux Mint

This guide explains how to configure Xdebug to work with VSCodium for PHP debugging on Linux Mint.

🧱 1. Install Xdebug

First, make sure PHP is installed:

php -v

Then install Xdebug (example for PHP 8.2):

sudo apt update
sudo apt install php-xdebug

Verify that it’s installed:

php -m | grep xdebug

You should see xdebug in the list.

⚙️ 2. Configure Xdebug

Locate your Xdebug configuration file. It’s usually found in one of these locations:

  • /etc/php/8.2/cli/conf.d/20-xdebug.ini (for CLI)
  • /etc/php/8.2/apache2/conf.d/20-xdebug.ini (for Apache)

Open it and add or edit the following lines:

zend_extension=xdebug.so

; Enable debugging mode
xdebug.mode=debug
xdebug.start_with_request=yes

; Communication settings
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Notes:

  • xdebug.mode=debug enables debugging functionality.
  • xdebug.start_with_request=yes makes Xdebug start automatically on every PHP request.
  • Port 9003 is the default for Xdebug 3.x (older versions used 9000).

Restart PHP to apply changes:

sudo systemctl restart apache2
# or, if you’re using PHP-FPM:
sudo systemctl restart php8.2-fpm

Verify configuration:

php -i | grep xdebug

🧩 3. Configure VSCodium

  1. Install the PHP Debug extension

    • Open Extensions (Ctrl+Shift+X)
    • Search for PHP Debug
    • Install it (author: Felix Becker)

  2. Create a launch configuration

    • Open Run and Debug (Ctrl+Shift+D)
    • Click “create a launch.json file”
    • Choose PHP

    It should generate something like this:

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

  3. Start debugging

    • Select “Listen for Xdebug” from the debug dropdown.
    • Click the Run (▶️) button.
    • Set breakpoints in your PHP files.

🧪 4. Test the Setup

Create a test file, for example test.php:

<?php
$foo = "Hello Xdebug";
echo $foo;

Place a breakpoint on the $foo = ... line.
Start the debug listener in VSCodium and run the script:

php test.php

If everything is set up correctly, VSCodium will stop at the breakpoint.

🧠 Tips & Troubleshooting

  • Port conflict:
    Xdebug 3 uses port 9003 by default. Make sure it’s not blocked by a firewall or used by another service.

  • No breakpoints hit?

    • Ensure xdebug.mode=debug is set.
    • Verify xdebug.client_host=127.0.0.1 (for local setups).
    • Check that you’re running the same PHP environment that Xdebug is configured for (CLI vs Apache/FPM).

  • Optional browser debugging:
    If debugging a web app, you can use the Xdebug helper browser extension to start and stop debug sessions manually.

âś… You now have a fully working Xdebug setup with VSCodium on Linux Mint!