Xdebug on DDEV

DDEV comes with Xde­bug built in, and it is eas­i­ly enabled via a con­fig­u­ra­tion option or com­mand line command. 

Before we jump into this infor­ma­tion: I have an entire course, called Debug­ging with Xde­bug, on how to use Xde­bug for debug­ging. It cov­ers debug­ging with DDEV in Php­Storm and VSCode, includ­ing how to debug Craft plu­g­ins and even Twig templates. 

The course also has a com­pan­ion Craft CMS plu­g­in, avail­able in the Craft Plu­g­in Store, that you can use as a learn­ing tool. The plu­g­in has bugs that we find and fix. It also can, quite amus­ing­ly, make bugs crawl all over your Craft CMS dashboard.

For this video, we won’t cov­er how to set up Xde­bug with your IDE; that infor­ma­tion is already thor­ough­ly cov­ered in the course as men­tioned earlier.

So, as a com­pan­ion to this course, please watch the Xde­bug course. I think you’ll like it!

DDEV ships with Xde­bug off by default. To enable Xde­bug in DDEV, we have two options:

1. enable it on the command
2. update our DDEV con­fig­u­ra­tion file

The dif­fer­ence between the two is that with the com­mand line com­mand you can eas­i­ly enable and dis­able Xde­bug only when you need it. The con­fig­u­ra­tion file allows you to always default to xde­bug enabled, if you just want to run debug mode instead of tog­gling it off and on. Your site will per­form a bit slow­er with Xde­bug enabled, so you might not want it on all the time.

Let’s say we need to start a debug­ging ses­sion to work through an issue with a tem­plate or a mod­ule. To enable Xde­bug on the com­mand line, we use the xdebug subcommand:

$ ddev xdebug enable

This enables Xde­bug so it is run­ning as a PHP exten­sion. Now it will be avail­able to call back to our IDE on port 9000 when it receives a HTTP request.

Once we’re done, we dis­able Xde­bug with the same com­mand but pass­ing in disable as the argument.

$ ddev xdebug disable

For some projects, you may want to have an Xde­bug enabled the entire time. For this sce­nario, we’ll enable it in the DDEV con­fig file. This is the same file we used to update the TLD, and add addi­tion­al sites for a Craft mul­ti-site project.

In the con­fig file, which is locat­ed in your project at .ddev/config.yaml, we change xdebug_enabled from its default of false to true. Now when DDEV starts, it will enable Xde­bug and keep it enabled until you dis­able it. 

xdebug_enabled: true

If DDEV is already run­ning, we need to restart it to pick up the change in the con­fig­u­ra­tion file. 

$ ddev restart

Now if we run

$ ddev exec php -v

we should see Xde­bug list­ed along with the PHP ver­sion. That means it’s been loaded as part of PHP!

For com­plete cov­er­age on how to use Xde­bug with Craft CMS, includ­ing how to debug Twig tem­plates, check out my course Debug­ging with Xde­bug, which is also avail­able for all pre­mi­um members!