Spent most of yesterday fiddling with Xdebug trying to get it to work. It used to work perfectly but at some point in the last 2-years it’s broken. I’m 90% there but there’s one more thing I need to fix.
I’m using a Mac running macOS Monterey and Local 6.4.3.
Here’s how I got it 90% working:
Firstly, to clarify:
- Any site using < PHP 7.4 uses Xdebug 2 on port 9000 in Local.
- Any site using > PHP 7.4 uses Xdebug 3 on port 9003 in Local.
I was able to get the code stepper to work by using the following Local settings:
- Local > Preferences > Advanced > Router mode > Site Domains
and then using the following site settings:
- Web server: nginx (not sure this is important)
- PHP version: 8.0.22
- Database: MySQL (not sure this is important)
I have been using the Xdebug + Local extension, which can be found here: GitHub - pixeljar/local-addon-xdebug-vscode
It certainly helps as a one-click solution to create the required .vscode folder with the launch.json file inside but it’s not currently fully compatible with Xdebug 3, so I’ve tweaked the output. I’ll get to that in a minute.
Moving to VSCode, you need to have this PHP Debug extension installed and activated: PHP Debug - Visual Studio Marketplace
I’m not sure if this next bit is needed but I installed PHP 8 at the system level (since it’s no longer installed by default in macOS Monterey). I did this using brew install php, which installed version 8.1.10. I felt this was close enough to Local’s version of PHP but you can specify other versions if you need to. This put a php executable at /opt/homebrew/bin/php so I added this to my settings.json file in VSCode in the following way:
"php.debug.executablePath": "/opt/homebrew/bin/php", "php.validate.executablePath": "/opt/homebrew/bin/php"
If you use the Xdebug + VSCode extension in local, clicking the link under Tools > Xdebug + VS Code > Add run configuration to VS Code will add the required .vscode folder and launch.json file.
I’ve then edited this to use port 9003 instead of 9000 as Xdebug 3 uses port 9003 where as Xdebug 2 (which the extension supports), uses 9000.
Moving to the php.ini file, which’ll need modification. This can be found in site-folder > conf > php > php.ini.hbs where site-folder is the folder of your site, which can be reached by clicking the ‘Go to site folder’ under the name of the site in Local. I’ve removed all the xdebug. settings that Flywheel added and have replaced with the following. I’ve added this below the entries for opcache but before the [Pcre] entries:
[xdebug]
{{#if os.windows}}
zend_extension = php_xdebug.dll
{{else}}
zend_extension = {{extensionsDir}}/xdebug.so
{{/if}}
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.idekey = VSCODE
The crucial part, I found to making the code stepper work in VSCode was the xdebug.idekey = VSCODE line. The other two lines should replace all the other lines that Local usually adds for Xdebug 2, with these more consolidated lines which are for Xdebug 3.
After saving that and restarting the site in local, you should be able to debug by opening the /app/public folder in VSCode, adding a breakpoint, and then pressing F5 to run Xdebug. If it then shows a pop-up with some options, choose ‘PHP’. Then open the site using the site domain (e.g. https://your-site.local). It should pause in VSCode when it hits the breakpoint, providing that it does.
Using the above, I was able to get everything working except for using http://localhost:9003 for debugging. When visiting this page, it just constantly tries to load but never does and never times out. Interestingly, I think this is related to how Local connects to localhost in general as, using Gulp and http://localhost:3000 for browserSync has recently stopped working too. It’s like Local doesn’t want to forward the site through localhost anymore, even though it was working around a month ago. Everything else seems to have stayed the same in my dev set-up so it’s possible a recent update to Local, or macOS has caused an issue.
If anyone knows where the problem might be, please let me know.
Hope the above helps someone.
Jack
