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'
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.