Debug Drupal using Dephpugger

Moses Liao GZ
Sep 26, 2018 · 4 min read
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]

FROM drupal:8.5.6-apacheRUN apt-get updateRUN apt-get install -y git-core# Install Composer
RUN curl -sS https://getcomposer.org/installer | 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.

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'services:
drupal:
image: php:dephpugger
container_name: "drupal"
ports:
- "80:80"
volumes:
- .:/var/www/html
mysqldb:
image: mysql:5.7.22
container_name: "mysqldb"
command: --default-authentication-plugin=mysql_native_password
ports:
- '3306:3306'
volumes:
- mysql_data:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: $DB_ROOT_PASSWORD
MYSQL_DATABASE: $DB_NAME
volumes:
mysql_data:

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_____             _
| __ \ | |
| | | | ___ _ __ | |__ _ __ _ _ __ _ __ _ ___ _ __
| | | |/ _ \ '_ \| '_ \| '_ \| | | |/ _` |/ _` |/ _ \ '__|
| |__| | __/ |_) | | | | |_) | |_| | (_| | (_| | __/ |
|_____/ \___| .__/|_| |_| .__/ \__,_|\__, |\__, |\___|_|
| | | | __/ | __/ |
|_| |_| |___/ |___/
Server - Version: v1.2.2
--- Listening on port 9002 ---

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.

Moses Liao GZ

Written by

Tech lead in Singapore Press Holdings

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