Debug Drupal using Dephpugger

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]

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.

debugger:
host: 0.0.0.0 # default: localhost
port: 9002 # default: 9005
lineOffset: 10 # default: 6
server:
host: 0.0.0.0 # default: localhost
port: 80 # default: 8888
path: /var/www/html/
file: .ht.router.php

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

version: '3'

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

drupal |
drupal | _____ _
drupal | | __ \ | |
drupal | | | | | ___ _ __ | |__ _ __ _ _ __ _ __ _ ___ _ __
drupal | | | | |/ _ \ '_ \| '_ \| '_ \| | | |/ _` |/ _` |/ _ \ '__
drupal | | |__| | __/ |_) | | | | |_) | |_| | (_| | (_| | __/ |
drupal | |_____/ \___| .__/|_| |_| .__/ \__,_|\__, |\__, |\___|_|
drupal | | | | | __/ | __/ |
drupal | |_| |_| |___/ |___/
drupal |
drupal | Server - Version: v1.2.2
drupal | Running command: /usr/local/bin/php -S 0.0.0.0:80 -t /var/www/html/ -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9002 -dxdebug.remote_host=0.0.0.0 -dxdebug.remote_connect_back=0 /var/www/html/.ht.router.php
drupal |
drupal | Access in 0.0.0.0:80
drupal |

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:

#~: docker-compose run drupal vendor/bin/dephpugger debug

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

Adding a break command

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

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

say bye bye to dpm

Conclusions

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.

Cloud and site reliability enthusiasts. AWS SA Associate certified

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