Debug Drupal using Dephpugger

Moses Liao GZ
Sep 26, 2018 · 4 min read
Image for post
Image for post
save me! I am trapped!

Dephpugger is an excellent tool for debugging PHP tools. Inspired by Ruby on Rails’s byebug gem, Dephpugger allows php developers debug your php projects regardless of the framework used.

And I managed to get it to work with the following tech stack:

  • PHP 7.2
  • Drupal 8.56

First I start off by downloading drupal 8.56. It comes along with a composer.json file. Run composer require “tacnoman/dephpugger”:”dev-master” to install the package

Build this Dockerfile docker build -t php:dephpugger [Dockerfile location]

RUN apt-get updateRUN apt-get install -y git-core# Install Composer
RUN curl -sS | php -- --install-dir=/usr/local/bin --filename=composer
RUN pecl update-channelsRUN pecl install xdebug && docker-php-ext-enable xdebugRUN docker-php-ext-install socketsRUN apt autoremove -y apache2CMD ["php", "vendor/bin/dephpugger", "server"]

Bear in mind that dephpugger needs both PHPxdebug and socket extensions to work, so do not use this for production as there are many many overheads. Only use this Dockerfile or development.

Also I remove apache2 as it is not needed.

Add the following .dephpugger.ymlfile into the root folder of your drupal setup.

Bear in mind that the server file MUST point to .ht.router.php in order to work, as dephpugger uses php web server, not apache2

Then add this docker-compose.yml file in

image: php:dephpugger
container_name: "drupal"
- "80:80"
- .:/var/www/html
image: mysql:5.7.22
container_name: "mysqldb"
command: --default-authentication-plugin=mysql_native_password
- '3306:3306'
- mysql_data:/var/lib/mysql

Next, run docker-compose up. You will see this:

You will notice the that they pick up values from .dephpugger.yml file and run the php server.

So the server part is running, now is to run the debug part. Open a new console and run docker exec -it [DRUPAL_CONTAINER_NAME] bash. Once in the container, run vendor/bin/dephpugger debug. You will see the following:

_____             _
| __ \ | |
| | | | ___ _ __ | |__ _ __ _ _ __ _ __ _ ___ _ __
| | | |/ _ \ '_ \| '_ \| '_ \| | | |/ _` |/ _` |/ _ \ '__|
| |__| | __/ |_) | | | | |_) | |_| | (_| | (_| | __/ |
|_____/ \___| .__/|_| |_| .__/ \__,_|\__, |\__, |\___|_|
| | | | __/ | __/ |
|_| |_| |___/ |___/
Server - Version: v1.2.2
--- Listening on port 9002 ---

Add a xdebug_break() into any of the functions with drupal.

Image for post
Image for post
Adding a break command

Do a site refresh and you should see something on the debugger console:

Image for post
Image for post
I wish I can stop time like this, like Dr. Strange

you can hit next or n to go to the next function or query the attribute value

Image for post
Image for post
say bye bye to dpm


Drupal have many many debug tools, but as a developer with a little RoR background, dephpugger suits me better as I can see how Drupal programme flows using the next command, and it is closer to byebug.

But do be aware of the downside. Using xdebug within docker is quite a lot of overheads and it slows down your system, and I want to repeat, don’t use this library in production.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store