Laradock + XDebug + MS Code? No problem!
I recently got Laradock’s XDebug and MS Code to talk to each other. Setting it up, was a slightly crooked path and a discovery that getting it to work is a sum of its parts. Sharing is caring, ladies and gents, so I figured I’d give you all the bits and pieces here in one place.
What you’ll need:
- Laradock set up and already running an Nginx server and PHP. Soz, setting up Laradock is too lengthy to cover in this tutorial. There are plenty of resources out there, mainly Laradock’s own installation tutorial.
- basic knowledge of OSX terminal commands
- MS Code installed
- You also need the excellent Php-debug for MS Code extension by Felix Becker installed.
Assuming you’ve got Laradock up and running, this tutorial should take you about 30 min to complete.
Laradock
Just a brief section for those who ended up in this tute and don’t yet know about Laradock.. I won’t spend much time advertising it, just a little :) If you’re a PHP dev, you already know about it or at least have heard about it. If not, take a look. Laradock is basically a collection of Docker containers that can be orchestrated to build into a PHP/Nginx/MySQL environment with minimal effort. It provides every developer with the same basic environment, regardless of whether they’re on Linux, OSX or Windows. Goodbye, “works for me”. And because it’s running off Docker, it won’t mess up your system defaults and you get to decide how much system resources its virtual machine uses. Pretty neat. Laradock is actually a lot more than a PHP stack: it comes with Symfony, Laravel, Redis, Mongo and goshdarn what else bundled. And, with a little tender love and care, you can base your Continuous Deployment setup on the same containers. Nerdalicious.
XDebug
Have you ever needed to find out some variables within a whole nested array of other variables, and confirm some variable gets updated? And, have you had to use var_dump or print_r or echo to see your vars? Painful and time-consuming. Enter XDebug. It integrates with the code in your MS Code environment and gives you the option of stopping a PHP script mid-stream and examining all the system and user set variables, as well as step forward, into and out of functions. You’ll see, wondrous events doth transpireth before thy very eyes.
How this thing works
For those who have done a local setup and used XDebug in the past and have just recently started using Docker, here’s a short explanation to why this is slightly different:
A virtual container, in this case Laradock’s PHP-FPM container, is an entity that’s separated from your machine’s native environment. Therefore, when you’re wanting XDebug to do something useful from a container, you need to make sure that XDebug (running in the Laradock container) can reach your MS Code environment (running on your machine), which is now listening to incoming connections. That’s why you need to define the rules of this connection differently to running everything on your localhost.
Just wanted to get that off my chest :)
Step 1: Activate XDebug in Laradock
In your Laradock .env file (the one with all the central configs) set
WORKSPACE_INSTALL_XDEBUG=true
Then, edit the Laradock xdebug.ini files. Yeap, it’s in two places, don’t ask why. The locations are Laradock/PHP-FPM/xdebug.ini and Laradock/workspace/xdebug.ini. Insert this config:
xdebug.remote_enable=1
xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.remote_connect_back=0
xdebug.remote_handler=dbgp
xdebug.max_nesting_level=250
xdebug.remote_log=”/var/www/xdebug_log/xdebug_docker.log”
What’s happening in the above config is that you’re:
- enabling remote debugging
- defining the remote host to be your localhost’s IP address (yeap, special namespace defined for macs, see https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host)
- setting remote debugging to start automatically and
- using the dbgp handler (you don’t need to know what that is)
- The max_nesting_level has to do with the depth of variable/array structure that XDebug drills into, I think. I’ve never needed to change that.
Lastly, I’ve enabled XDebug logging, so I can.. debug XDebug :) For that to work, create an xdebug_log folder for the log file into what you’ve defined as your synced workspace, i.e. what folder /var/www/ is mapped to in your folder structure. Mine is Users/lauri/code/xdebug_log. That will make sure that everything XDebug does (or fails trying to) is logged into that folder.
All done configuring Laradock! Now it’s time to rebuild and restart your Laradock PHP-FPM container, since you’ve made some fundamental changes. Normally you’d just restart, but since you’re including a new module, you need to actually build the container so Xdebug gets added.
So, run this from the terminal in your Laradock root:
laradock $ docker-compose build php-fpm
You’ll get a bunch of building output. You’ll see some red, but the reds I’ve gotten are notification only.
After that, restart:
laradock $ docker-compose down && docker-compose up -d nginx mysql
Alrighty, moving on to MS Code.
Step 2: MS code setup
We’re using the excellent php-debug plugin built by Felix Becker. Props!
Here’s the Gitter forum for the MS Code php-debug extension, full of like-minded individuals, more knowledgeable than yours truly, many of who have gone through the same process of setup and are glad to offer advice. As a matter of fact, they inspired me to write this tutorial :)
Then set up MS Code to listen to incoming connections from Laradock:
- Go to Debug view
- Add a config
- Fire up Debug with that config
Adding a config creates a launch.json file that MS Code uses for its settings (all configuration of the MS Code environment is by using JSON files). Here’s what launch.json needs to contain:
So, explaining the above:
- I’m logging what happens in my launch config
- This launch config is specifically for PHP
- An incoming request (from Laradock) launches the MS Code debugger,
- Those requests are expected to be coming from port 9000 as previously defined in xdebug.ini.
- The code xdebug is supposed to be using for the session is mapped into this folder.
About the last item: you need to explain to XDebug where it can find its equivalent Laradock-synced files on your local system so it can open them up in the editor and allow stepping forward, in and out. This is achieved by the pathMappings array in your launch.json. Remember, for each project you need to set up one entry here. Think of this as the holy union between your project workspace files and MS Code.
Example: I work on project1 that’s in folder Users/lauri/code/project1. Laradock is set up to /var/www which is mapped to my directory Users/lauri/code. Therefore a project that’s in Users/lauri/code/project1 has a mapping that looks like this:
“pathMappings”: {
“/var/www/project1”:”/Users/lauri/code/project1"
}
Now, after you’ve added the config and fired up MS Code debug, an orange bar should appear at the bottom of your MS Code environment:
What you can also look out for when reloading your page is output in the debug console of MS Code. You should be seeing incoming request threads like this:
Okay, time to place some breakpoints.
Step 3: place a breakpoint
Add a breakpoint to your file. For the purpose of this tute, I’ve created a simple file, which contains just one line. The important thing is that you place the breakpoint onto a legit line of PHP, such as a function execution or a variable declaration. Make sure you validate the breakpoint by reloading the ms code XDebug listener.
If the breakpoint is a hollow circle, that means you need to refresh the debugger to validate that breakpoint. You can do so in the debug bar that’s now appeared when you started listening to incoming connections.
Step 4: toggle XDebug on and off
Laradock provides a simple way to add or remove XDebug to or from your project. It’s handy, because you don’t always need XDebug and it slows down things slightly so you’ll want to switch it on only when you’re actually debugging. Laradock has provided these handy commands, which are run from the Laradock folder:
laradock $ ./php-fpm/xdebug start
laradock $ ./php-fpm/xdebug stop
laradock $ ./php-fpm/xdebug status
Step 5 (optional): adjust your Nginx timeout
As an additional thingy for your xdebugging pleasure, you may want to adjust your keepalive_timeout in your nxing.conf file. That’s optional, but I’ve found it to be helpful to set that to something like 300 seconds, so your script doesn’t time out while you’re debugging. Remember to restart (no need to rebuild) your Laradock instance after changing that.
Here’s a tutorial on using the MS Code debugger. That’s a good read on how to get the most out of your new setup.
Happy XDebugging!
Kind Regards,
Lauri Jalonen
