Retro Style
Configure Acquia Dev Desktop to use Xdebug on Windows
Debugging like it’s 1999!
I remember when I landed my first job in continental United States, having moved from insular Puerto Rico to New York after the 2007–2009 Great Recession.
It was at the tony New York City headquarters of Time Out New York, back when Time Out was a separate entity from Time Out London. They were switching from a Java backend to a PHP/Drupal-based stack, and that’s where me and two other new Drupal developers came in. The sole remaining Java developer in the company (who dabbled in PHP), had requisitioned 3 new Windows 7 machines for us and installed XAMPP on them. XAMPP was (and I think it’s still active) a LAMP distribution for Windows. God, was running Drush on that thing painfully slow. Needless to say, these were the prime Drupal 6 days (released in 2008).
Sometime later the company founded by Drupal creator Dries Buytaert (Acquia) launched Acquia Dev Desktop to facilitate onboarding businesses and users to their main offering— Drupal professional services. Acquia Dev Desktop is very similar, if not a carbon copy of XAMPP. Which means that as of 2020, this is a 10+ years old technology that I will be writing about here today. This is some serious software paleontology here!
However, as I wrote in this previous Using Acquia Dev Desktop + Visual Studio Code on Windows 10 story, while scouting the job market for Drupal I found out a large number of entities out there still using Dev Desktop. Most of them didn’t quite grip what Docker was yet. And so that brings us to today’s post — how to add XDebug to this veritable product (Dev Desktop), but with a modern twist: using Visual Studio Code.
Prerequisites
In this tutorial I assume you have the following dependencies already installed:
- Visual Studio Code
- PHP Debug for Visual Studio Code
- Xdebug Helper for Google Chrome
- Acquia Dev Desktop
- A Drupal site up and running in Acquia Dev Desktop that you can use to test XDebug (optional).
Gathering Requirements
There are two pieces of information that you need in order to determine what version of Xdebug to download for Windows: 1) PHP architecture, x32 or x64, and; 2) Thread Safety.
.
Requirement #1: PHP architecture
After installing Drupal with Acquia Dev Desktop, you can check the architecture of the PHP in Dev Desktop by visiting your Drupal sites’ phpinfo() page at admin/reports/status/php:
The architecture field should indicate if the PHP version Dev Desktop is using is x32 or x64.
In my case the PHP info page above indicates a x64 architecture.
.
Requirement #2: Thread Safe (TS) vs Non-Thread Safe (NTS)
The second step to determine the type of PHP extensions you can install is to determine thread safety.
On the same phpinfo() page, look for the Thread Safety section:
If it says that Thread Safety is enabled, then when installing PHP extensions you will need to make sure they are Thread Safe (TS). Non-Thread Safe extensions are usually denoted by the acronym NTS.
With those two required pieces of information set, I can now move to download the specific version of Xdebug for Dev Desktop on Windows, according to it’s thread safety and architecture. Downloading an extension with the wrong thread safety and/or architecture will not work!
Downloading Xdebug for Windows
Head over to xdebug.org, where you can find a link to the downloads section:
The Thread Safe extensions are denominated by the acronym TS, and the x64 architecture extensions specify so in parenthesis (64 bit).
After right-clicking the appropriate download link, I save the extension (ending in a .dll filename) to my users’ Downloads directory in Windows.
Rename and move Xdebug
.
I will need to move the downloaded extension to a place where Dev Desktop can find it, and rename it to php_xdebug.dll. I will be doing so via the command line, using cmd.exe.
In order to successfully move the downloaded extension to C:\Program Files (x86)\DevDesktop, you will need to open cmd.exe (or PowerShell) with Administrative Privileges, because Program Files is a privileged location.
After opening cmd.exe, I can rename and move downloaded extension to the path Dev Desktop expects with three commands:
cd %HOMEDRIVE%\Users\%USERNAME%\Downloadscp php_xdebug-2.9.6-7.1-vc14-x86_64.dll php_xdebug.dllmv php_xdebug.dll "C:\Program Files (x86)\DevDesktop\php7_1_x64\ext"
In the example above I’m using the 7.1.x version of PHP in Dev Desktop.
If you get an error message similar to:
mv: cannot move to 'C:\Program Files (x86)\DevDesktop\php7_1_x64\ext/php_xdebug.dll': Permission deniedJust remember to open your Windows shell (Cmd.exe) with administrator permissions.
To verify that the move command was successful, you can run the list command:
ls -la "C:\Program Files (x86)\DevDesktop\php7_1_x64\ext\php_xdebug.dll"-rwxr-xr-x 1 wario 197609 235520 Jun 17 23:58 'C:\Program Files (x86)\DevDesktop\php7_1_x64\ext\php_xdebug.dll'
After downloading, renaming, and moving the XDebug extension to it’s expected location, it’s time to modify the Dev Desktop php.ini settings.
.
Add Xdebug to php.ini
.
In the Dev Desktop Settings -> Config -> Stack configuration file, I select the second option from the menu, then click Edit:
After a Notepad.exe is opened with the selected php.ini file, I insert the following template I found from this Acquia guide for Using XDebug on Dev Desktop.
[xdebug]
zend_extension="C:\Program Files (x86)\DevDesktop\php7_1_x64\ext\php_xdebug.dll"
xdebug.remote_autostart=off ; Do not run Xdebug on every page request
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=localhost
xdebug.remote_port=9000With the XDebug extension placed in the proper location, and the php.ini edits in place, open the Acquia Dev Desktop control panel and restart it.
.
Verify that Xdebug is installed
.
After 1) Downloading the correct Xdebug binary; 2) Moving it to the proper location, and; 3) Modifying the corresponding php.ini, now it is time to 4) Verify that it is installed!
Assuming you have already restarted Dev Desktop, if you head to the phpinfo() page at admin/reports/status/php, you should notice a line that says with Xdebug v[VERSION] :
If you search for XDebug on this page, you should see a brand new section with all the XDebug defaults:
And with this it is confirmed that Xdebug has been successfully added to your Dev Desktop install.
Configure Visual Studio Code for Xdebug
When creating a new PHP project in Studio Code, there is no launch.json configuration. If you haven’t already installed PHP Debug for Visual Studio Code, you will need to install it now for the next step.
With PHP Debug for Visual Studio Code installed, go to the Run menu and select Add Configuration:
A drop down appears with a list of launch templates you can select:
Select the PHP template suggestion. This will create a new launch.json file for your new project:
This default template creates to new launch configurations: 1) Listen for Xdebug, and 2) Launch currently open script.
The default template worked for me without modifying a single line.
Configure Google Chrome and test
.
In my setup, I am using the Xdebug helper extension for Google Chrome.
If you have not installed the extension, go ahead and install it. I did not have to modify any Chrome extension settings for Xdebug to work in this example.
Without modifying anything at all in the default launch.json template, I am going to launch the Listen for Xdebug configuration, by selecting Listen for Xdebug from the Run option, and clicking on the little green arrow next to it:
This instructs Xdebug to intercept and pause on any incoming requests to the PHP project.
Next, assuming Acquia Dev Desktop is running, and all the previous steps have been followed, I open the status page of my example Dev Desktop site in Google Chrome. Before the page finishes loading, Visual Studio Code is brought to focus in Windows. Xdebug is working.
Here is a screenshot of a breakpoint I put in my example site’s setting.php getting hit:
You can read more on how to use the Visual Studio Code debugger here, and here.
And that concludes this story — how to use the venerable Acquia Dev Desktop LAMP distribution with the new and exciting Visual Studio Code, along with Xdebug.
Remember that on my previous post I covered the basics of setting PHP Intellisense for Dev Desktop, which you’ll need to get basic file navigation and function suggestions for your Drupal projects.
I’ll leave you with some pleasurable and inspirational Japanese meme music:
Happy Drupaling!
