DDEV comes with Xdebug built in, and it is easily enabled via a configuration option or command line command.
DDEV comes with Xdebug built in, and it is easily enabled via a configuration option or command line command.
Before we jump into this information: I have an entire course, called Debugging with Xdebug, on how to use Xdebug for debugging. It covers debugging with DDEV in PhpStorm and VSCode, including how to debug Craft plugins and even Twig templates.
The course also has a companion Craft CMS plugin, available in the Craft Plugin Store, that you can use as a learning tool. The plugin has bugs that we find and fix. It also can, quite amusingly, make bugs crawl all over your Craft CMS dashboard.
For this video, we won’t cover how to set up Xdebug with your IDE; that information is already thoroughly covered in the course as mentioned earlier.
So, as a companion to this course, please watch the Xdebug course. I think you’ll like it!
DDEV ships with Xdebug off by default. To enable Xdebug in DDEV, we have two options:
The difference between the two is that with the command line command you can easily enable and disable Xdebug only when you need it. The configuration file allows you to always default to xdebug enabled, if you just want to run debug mode instead of toggling it off and on. Your site will perform a bit slower with Xdebug enabled, so you might not want it on all the time.
Let’s say we need to start a debugging session to work through an issue with a template or a module. To enable Xdebug on the command line, we use the xdebug subcommand:
$ ddev xdebug enable
This enables Xdebug so it is running as a PHP extension. Now it will be available to call back to our IDE on port 9000 when it receives a HTTP request.
Once we’re done, we disable Xdebug with the same command but passing in disable as the argument.
$ ddev xdebug disable
For some projects, you may want to have an Xdebug enabled the entire time. For this scenario, we’ll enable it in the DDEV config file. This is the same file we used to update the TLD, and add additional sites for a Craft multi-site project.
In the config file, which is located 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 Xdebug and keep it enabled until you disable it.
xdebug_enabled: true
If DDEV is already running, we need to restart it to pick up the change in the configuration file.
$ ddev restart
Now if we run
$ ddev exec php -v
we should see Xdebug listed along with the PHP version. That means it’s been loaded as part of PHP!
For complete coverage on how to use Xdebug with Craft CMS, including how to debug Twig templates, check out my course Debugging with Xdebug, which is also available for all premium members!