Enable xdebug on demand in your local docker environment

Reading Time: 2 minutes

Xdebug is an essential tool for me when I develop PHP applications (kudos to Derick Rethans for his dedication over the many years). Yet it admittedly slows down code execution. It gets worse when you run docker on a Mac. You are screwed if you run a really complex application like Typo3 in this setup (got a bit of a dejavu here). Wouldn’t it be cool then to only enable xdebug on demand in your local docker environment?

For example, I was working on a Typo3 project with lots of content in up to 10 languages. Without xdebug, one huge page (the dreaded ID 6) loads in 1.2 minutes, which is already really bad. But with xdebug enabled it jumps up to 6.5 minutes! You simply can’t work like that.

Surely this is an extreme example, but also on smaller pages it felt really slow with xdebug enabled. I kept it enabled though because I was too lazy to always rebuild my docker container…

Xdebug toggle script

So what I need is an easy way to enable (and disable) xdebug in my local docker setup easily. Finally, I figured out a solution that works very well for me:

https://gist.github.com/carstenwindler/b330028c41c453c905cbe0801470afd2

This little script allows you to enable or disable xdebug in seconds using your command line:

./xdebug.sh disable

to disable it and, well you probably guessed it,

./xdebug.sh enable

to enable it again.

Absolutely no rocket science here. Under the hood, the script simply moves the docker-php-ext-xdebug.ini into a directory outside of /usr/local/etc/php/conf.d. Upon restart of the app container, PHP loads completely without xdebug. To enable it again, the file is copied back.

Some things to keep in mind:

  • It is written for the official PHP docker image on Docker Hub (using the docker-php-ext-xdebug.ini – yet this can be adapted to your needs quickly)
  • It expects the PHP service to be called “app” in docker-compose.yml. This is easily adaptable to your needs as well.

I’m not an experienced bash programmer, so there is surely room for improvement. I’m happy about suggestions to improve it!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.