Home
Using XDebug in Laravel Sail (VSCODE)
Programming

Using XDebug in Laravel Sail (VSCODE)

January 20, 2025

Hi guys 👋🏾, in this article I will be writing about how I got to set up XDebug to work in my Visual Studio Code editor for both my testing environment through the terminal and for browser request.

For someone pampered with the luxury of having a seamless debugging experience in Visual Studio IDE for C#, I also wanted to enjoy that comfort in a Laravel sail project setup. This led me to some exploration and luckily I found a light at the end of the tunnel.

Requirements

  • Visual Studio Code
  • PHP Debug Extension (here)
  • PHP and Composer
  • XDebug Browser Extension(here)

Browser Debugging

  • I created a Laravel project setup called “mysail“
           composer create-project laravel/laravel mysail
  • I navigated to the newly created project 
          cd mysail
  • I installed sail 
           php artisan sail:install
  • I added this environment variable to activate XDEBUG for debugging sessions
           SAIL_XDEBUG_MODE=develop,debug,coverage
  • I started my sail environment 
./vendor/bin/sail up
  • I opened a new terminal and ran my migrations
./vendor/bin/sail artisan migrate
  • I clicked on the “Run and Debug” option in VSCode
  • I clicked on the “create a launch.json file“
  • I clicked on the “PHP(XDebug)” option which opened some pre-configured debugging setup
  • I looked for the one that had “Listen for Xdebug” and changed it from:
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },

     to this


        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}"
            }
        },

The mapping enables the debugger to locate the right files to monitor set breakpoints.

  • In my browser, I activated the XDebug browser extension by clicking on the “Debug” option of the extension
  • I added a breakpoint to the home route to test if it works
  • I clicked on the “Listen for Xdebug” button to activate the debugging session
  • Now navigating to the website URL (localhost) stops exactly at line 6
  • Yay!! it works, next I wanted to ensure I could use it to debug my test.
  • I tried using the default scaffolded test created in a new Laravel project
  • I added a breakpoint here:
  • I opened a new terminal and ran this “./vendor/bin/sail debug test –filter test_the_application_returns_a_successful_response” instead of “./vendor/bin/sail artisan test –filter test_the_application_returns_a_successful_response”
  • Note the difference in replacing “artisan” with “debug“
  • And that worked as well

Things to note:

  • Set your env: SAIL_XDEBUG_MODE=debug,debug,coverage before running “sail up“
  • Add the path mapping to your PHP debugger VSCode configuration
  • Activate the XDebug browser extension by clicking the “Debug” option when debugging browser requests.
  • For your terminal debugging activities replace the “artisan” command with the word “debug”

Thanks for reading and bye 👋🏾

Related Articles

About The Author

Samson Amaugo

I am Samson Amaugo. I am a full-stack developer and I specialize in DotNet and the MERN stack.

18 Comments

  1. Ceejay

    Great content

    January 20, 2025
  2. Ashkan Ebtekari

    I love how concise and straight to the point this article is. Great work as always, Samson. Thanks for sharing.

    January 21, 2025

Leave a Reply