Skip to content

Instantly share code, notes, and snippets.

@ahmadawais
Last active September 5, 2024 01:57
Show Gist options
  • Save ahmadawais/d6e809d45b8103b2b3a79fa8845f9995 to your computer and use it in GitHub Desktop.
Save ahmadawais/d6e809d45b8103b2b3a79fa8845f9995 to your computer and use it in GitHub Desktop.
Debug WordPress with Visual Studio Code | VSCode WordPress Debug Setup | WordPress xDebug Setup for Local by FlyWheel with VSCode | Part of the VSCode Learning Course → https://VSCode.pro

VSCode WordPress Debugging Setup: WordPress Xdebug Setup for Local by FlyWheel with VSCode


Consider supporting my work by purchasing the course this tutorial is a part of i.e. VSCode Power User

🚅 TL;DR

  • Make sure your Local by FlyWheel WordPress install is a custom install
  • Configure xdebug.remote_autostart = 1
  • Restart your site container in Local by FlyWheel to apply new settings
  • Install PHP Debugger extension and add PHP Debugger configuration with an extra property for the Listen for Xdebug section i.e. Add this "pathMappings": {"/app/public": "${workspaceRoot}"}

🚥 Detailed Tutorial

Here're are some easy steps to follow to make sure you can debug WordPress in Local by FlyWheel with VSCode:

1️⃣ Custom WordPress Install

Make sure your Local by FlyWheel WordPress install is a custom install.

  • ✅ Flywheel Local has Xdebug installed by default if you choose “Custom” instead of “Preferred” when setting up a new local environment.
  • ⚠️ You can check your already installed WP with the ”Site Setup” tab. If you can change the PHP version there, you have the “Custom” environment running and you have Xdebug installed.
  • ⚠️ If not, just export your site, import it back while creating a new site and this time choose “Custom”.

2️⃣ Configure Xdebug

Configure xdebug.remote_autostart = 1.

Now in the right environment we need to configure Xdebug for that:

  • Go to your local WordPress install path E.g. /PATH_WHERE_YOU_INSTALLED_WORDPRESS/conf/php/7.x.x/php.ini
  • Search for the [Xdebug] section
  • Add the following line in this section
xdebug.remote_autostart = 1

While only the above option is required but some 3rd party extension/plugin for local can sometimes change things so make sure in the [Xdebug] section all the following settings are set to 1 (only if your debugger is not working).

xdebug.scream = 1
xdebug.remote_enable = 1
xdebug.show_local_vars = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1

Save the php.ini file.

3️⃣ Restart The Site

Restart your site container in Local by FlyWheel to apply new settings.

  • On the left side menu, right click on your site
  • Select Restart option to restart the site.

Restart GIF

4️⃣ Visual Studio Code Configuration

Let's start configuration of VSCode:

  • First of all, install PHP Debug extension
  • Open your Local WordPress site project folder in VSCode. You should open the entire WordPress site folder i.e. /PATH_WHERE_YOU_INSTALLED_WORDPRESS/app/public
  • Go to the Debug view in VSCode COMMAND (⌘) + SHIFT (⇧) + D
  • Click “Add configuration” from the top toolbar
  • Select PHP and add the configuration
  • In the .vscode/launch.json file that was created inside the Listen for Xdebug section add "pathMappings": {"/app/public": "${workspaceRoot}"}

In short, your debug launch.json file will look like this:

{
	// Use IntelliSense to learn about possible attributes.
	// Hover to view descriptions of existing attributes.
	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Listen for Xdebug",
			"type": "php",
			"request": "launch",
			"port": 9000,
			"pathMappings": {
				"/app/public": "${workspaceRoot}"
			}
		},
		{
			"name": "Launch currently open script",
			"type": "php",
			"request": "launch",
			"program": "${file}",
			"cwd": "${fileDirname}",
			"port": 9000
		}
	]
}

5️⃣ Debug Your WordPress

Now go ahead and debug your WordPress app/plugin/theme and what not.

WP VSCode Debug GIF

  • After all this, click the play button next to “Listen for Xdebug” in the top debug bar
  • Create a breakpoint in your PHP code e.g. add this line and a breakpoint<?php $true_story = 'Ahmad is cool and VScode.pro is awesome!'; ?> to header.php of your theme
  • Browse your site and VSCode should pop up showing all your debug info

Remember to stop debugging process when you stop working. A good theme helps with that, install 🦄 Shades of Purple →

🔥 Extra Plugin (optional)

You can also install a local plugin called local-addon-xdebug-control for UI based control of Xdebug settings in your Local by FlyWheel software.

Make sure everything is set to yes for a sane debugging experience.

Add-on

Consider supporting my work by purchasing the course this tutorial is a part of i.e. VSCode Power User

For more follow @MrAhmadAwais

Peace! ✌️

@nathan-roberts
Copy link

Thanks for taking the time to detail this, lifesaver!!

@nyrsimon
Copy link

Still works in April 2020 - spent hours trying to get PHPStorm + Local + Xdebug to work and got this working in 10 mins - I guess I'm switching to VS Code :)

@ahmadawais
Copy link
Author

@nyrsimon glad you feel that way. Let me help you switch to VSCode and become a VSCode Power-user through my course. I recorded it only to help people like you, switching to VSCode who want to do it quickly and get the most out of it.

Click here to learn more → VSCode.pro

@byronkeet
Copy link

Hi Ahmad,

Just did an update to Local 5.4.1 and Xdebug no longer works. After trying to fix it for ages, I reverted back to 5.2.8 and it is back to working flawlessly. Any ideas?

@sumnermic
Copy link

Amazing stuff! This is a masterpiece! 🔥🙌🙌🙌

@ahmadawais
Copy link
Author

@sumnermic That's very kind of you to say! 🙌
Feel free to check out my VSCode.pro course which this tutorial is a part of. I explain the entire setup further in more detail with other workflow improvements like PHP Auto formatting based on WordPress coding standards.

Check it out at → VSCode.pro

@glaubersilva
Copy link

glaubersilva commented May 22, 2020

@byronkeet I had the same problems and after a few hours I decided to remove it:

 ,
"pathMappings": {
   "/app/public": "${workspaceRoot}"
}

And now everything is working properly! :)

@byronkeet
Copy link

@glaubersilva you are an absolute legend! Thank you so much for giving us the answer! Really appreciate it mate! And of course, @ahmadawais thank you for this entire thing!

@nyrsimon
Copy link

nyrsimon commented Jun 3, 2020

@glaubersilva - thanks also, I upgraded to 5.4.1 and encountered the same issue.

In case it's not clear to everybody YOU NEED TO REMOVE the pathmappings entry and it magically starts working again :)

@glaubersilva
Copy link

@byronkeet @nyrsimon Glad to help! :)

@stedesDev
Copy link

stedesDev commented Jul 14, 2020

Hi, How is life...
This is a real pain... we have one of the best IDE VS Code, one of the best Framework for a website WordPress... but we have nothing to debug. I tried every thing... Docker/now localwp

I'm on Ubuntu 20.04

But somethings bug me with and in the php.ini file

  • Mine is named php.ini.hbs is it normal
  • It is suppose to be config if we setup a custom WordPress
    but I have these strange line

[opcache]
{{#if os.windows}}
zend_extension = php_opcache.dll
{{else}}
zend_extension = {{extensions.opcache}} FOR ME IT IS BIZARRE no file name or path as per Steveromsay post
{{/if}}

[xdebug]
{{#if os.windows}}
zend_extension = php_xdebug.dll
{{else}}
zend_extension = {{extensions.xdebug}} FOR ME IT IS BIZARRE no file name or path
{{/if}}

If some one can post the magic solution for all of use...

Regards,
Steph

@ahmadawais
Copy link
Author

@stedesDev that is why I created → VSCode.pro course. Take it and learn it.

@stedesDev
Copy link

HUM... this is more publicity then an answer.
Regards,

@ahmadawais
Copy link
Author

ahmadawais commented Jul 15, 2020 via email

@finesaqib
Copy link

Dear Ahmad,

Thankyou for the post.

I have followed the instructions point by point. However, I am having a hard time setting up VSC.

Following Errors are displayed in VSC:
Cannot validate since no PHP executable is set. Use the setting 'php.validate.executablePath' to configure the PHP executable.

and

phpcs: Request workspace/configuration failed with message: Unable to locate phpcs. Please add phpcs to your global path or use composer dependency manager to install it in your project locally.

Thanking in anticipation

@ahmadawais
Copy link
Author

@finesaqib — I don't provide support here. You can purchase the course VSCode.pro and learn from the video lectures I teach. Peace! ✌️

@vanduc1102
Copy link

vanduc1102 commented May 17, 2021

This is super important, as I am debugging into a container

"pathMappings": {
  "/var/www/html/wp-content/plugins/abc-ecommerce": "${workspaceRoot}"
}

@JulioNobre
Copy link

JulioNobre commented Aug 5, 2022

In my case, after struggling to get proper debug working when application was launch on browser, I've decided to share it here.

Since Xdebug version dependes on PHP version, and since PHP.INI configuration has changed between Xdebug 2.x and Xdebug 3.x, consider using the following PHP.INI settings,

[Xdebug]

; Consider checking php_xdebug.dll file properties to get installed Xdebug version
zend_extension="D:\Programs\xammp\php\ext\php_xdebug.dll"

; Settings for Xdebug 2.x
xdebug.scream = 1
xdebug.remote_enable = 1
xdebug.show_local_vars = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1

; Settings for Xdebug 3.x
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port="9000" ; Default now is 9003

For further information, please check PHP Debug Adapter for Visual Studio Code official docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment