Drupal Debugging

Debugging is an essential skill for every Drupal developer. Whether you are working on custom modules, theming, API integrations, or performance issues, effective debugging helps you quickly identify and fix problems without breaking the site.

Drupal provides multiple built-in and contributed debugging tools, ranging from simple variable dumps to advanced profilers and log analyzers.

What is Debugging in Drupal?

Debugging in Drupal is the process of:

• Identifying errors, warnings, and unexpected behavior

• Inspecting variables, services, and execution flow

• Tracing issues in PHP, Twig, JavaScript, APIs, and configuration

• Improving performance and stability

Drupal debugging can be done at:

• PHP level

• Twig (theming) level

• Database level

• Routing & controller level

• Service container level

• Frontend (JS & AJAX)

Why Debugging is Important in Drupal?

Without proper debugging:

• Errors remain hidden

• Performance degrades

• Production issues are hard to trace

• Development becomes trial-and-error

With debugging:

• Faster development

• Cleaner code

• Better performance

• Easier maintenance

Common Drupal Debugging Options (Overview)

Drupal debugging tools can be broadly categorized into:

1. Drupal Core Debugging

2. PHP Debugging

3. Twig Debugging

4. Logging & Error Reporting

5. Database Debugging

6. Performance Debugging

7. Browser & Frontend Debugging

Let’s explore each in detail.

1. Enable Drupal Error Reporting (First Step)

Enable Error Display in settings.php

$config['system.logging']['error_level'] = 'verbose';

Why?

• Shows PHP notices, warnings, and errors

• Essential for local and dev environments

NOTE : Never enable verbose errors in production

2. Drupal Logging (Watchdog / Logger API)

Drupal logs all system messages using the Logger API.

View Logs

• Admin UI:
  /admin/reports/dblog

• Or via Drush:

drush watchdog:show

Log Custom Messages

\Drupal::logger('custom_module')->notice('This is a debug message');

Log Levels

• debug

• info

• notice

• warning

• error

• critical

Real Use Case

Debug API response failures or cron issues without breaking execution.

3. Using dump() and dd() (Development Module)

Install Devel Module

composer require drupal/devel
drush en devel

Usage

dump($node);
dd($user);

• dump() → prints variable

• dd() → prints and stops execution

Twig Debugging

{{ dump(content) }}

4. Twig Debugging (Theming)

Enable Twig Debugging in services.yml

 sites/development.services.yml

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

settings.php

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

What You Get

• HTML comments showing:

  • Template suggestions

  • Template file names

• Example:

<!-- THEME DEBUG -->
<!-- FILE NAME SUGGESTIONS:
   * node--article.html.twig
   * node.html.twig
-->

Real Use Case

Identify which Twig template Drupal is using.

5. Database Debugging (Queries & Performance)

Enable Query Logging

$databases['default']['default']['profiler'] = [
  'class' => '\Drupal\Core\Database\Log',
  'log' => TRUE,
];

Use Devel Query Log

• /devel/querylog

Drush

drush sqlq "SELECT * FROM node LIMIT 5"

Best For

• Slow pages

• N+1 query issues

• Heavy entity loads

6. PHP Debugging with Xdebug (Advanced)

Install Xdebug (Local)

pecl install xdebug

Enable in php.ini

xdebug.mode=debug
xdebug.start_with_request=yes

Use With:

• VS Code

• PHPStorm

What You Can Do

• Step through code line-by-line

• Inspect variables

• Track execution flow

Best For

• Complex service logic

• Custom plugins

• Event subscribers

7. Debugging Services & Dependency Injection

Inspect Services

\Drupal::service('entity_type.manager');

Dump Service Container

drush container:debug

drush container:debug | grep mail

8. Debugging Routes & Controllers

List Routes

drush router:debug

Debug Controller

dump($request->attributes->all());

9. JavaScript & AJAX Debugging

Enable Drupal JS Logging

console.log(Drupal.settings);

Debug AJAX Call

• Browser DevTools - Network tab

• Check JSON response

Common Issues

• Missing #ajax

• Wrong callback

• Invalid render array

10. Performance Debugging

Tools

• Devel module performance tab

• Browser DevTools

• Database query logs

What to Look For

• Excessive entity loads

• Render array complexity

• Cache misses

Best Practices for Drupal Debugging

✔ Debug locally or on dev environment only
✔ Never dump in production
✔ Use logging instead of dump() in prod
✔ Remove debug code before merge
✔ Combine logs + Xdebug for complex issues
✔ Know which tool fits the problem

When to Use Which Debugging Tool?

Common Debugging Mistakes

• Debugging directly on production

• Forgetting to disable Twig cache

• Leaving dd() in code

• Ignoring logs

• Overusing print statements