5 Ways to Debug Your Drupal 8 Projects

5 Ways to Debug Your Drupal 8 Projects

Admit it: there's no such thing as unbeatable “bug-proofing” web development technique! Bugs will hit your Drupal 8 projects sooner or latter and you need to have the most effective techniques under your belt for tracking and taking them down. Luckily, the “there's a module for any functionality you need in Drupal” stands when it comes to debugging, as well: you're “spoiled” with a plethora of ways to debug your Drupal 8 projects. And so, debugging turns into a matter of simply making up your mind, choosing the method that best suits your Drupal 8 project.

To lend you a hand, I've put together a selection for you, grouping the most popular techniques that range from the quick to use “track down and take out” ones, to the “top refined” methods of debugging! Here they are:

1. Disable Your Cache in Drupal Settings

What looks like an  enhancement brought to Drupal 8 can easily lead to... "hard to untangle” mess!

The fact that Drupal 8 caches much more stuff than its predecessors (rendered Twig templates and blocks here included!) can inevitable overly complicate things when we're coding, right?

With every change that we make we risk to be forced to rebuild the site cache, from scratch. 

The solution? Turning off caching during development! 

Whether it's a Drupal 8 module or a Drupal theme that you're developing, clear the Drupal 8 cache so you can visualize the changes you're making, the whole work in progress in real time!

And with the solution comes the great news, too: catching (most of it) can get disabled right from a Drupal setting file. How convenient!

Just copy (remember to rename it, too!) your sites/example.settings.local.php file to sites/default/settings.local.php.

Next, as you might already guess, you'll need to run a a couple of values uncomment/updating sessions, but I'm not going to get into details in this post about the lines that you need to focus on.

Then switch your focus to Twig and run a debugging session on this template, too: 

Drupal 8 comes with an out-of-the-mode theme debugging mode that you just need to... enable. How? By copying and pasting the following code either in the sites/default/services.yml file or in the development.services.yml one:

    debug: true    auto_reload: true
    cache: false

The ultimate convenience about using this mode is that you get to refine your searches (trying to discover which part of your HTML code has been written in which Twig templates) by the HTML comments surrounding your templates!

They'll inevitably contain matching suggestion templates pointing out to you precisely those templates (menus, blocks, pages...) that you need to override, as well as their file names.   

It's the debug: true parameter that will actually enable Twig's debugging process and trigger the display of the used Twig templates along with their paths.

Next, once you're done with those particular development/changes making tasks, you just need to rebuild your Drupal 8 cache and you're... good to go!

Note: printing a variable content takes nothing but inserting the following syntax in a Twig template:

{{ dump(my_variable) }}


2. Use the Devel Module

A module that will come in handy when you need to run a quick and easy “debugging” session on your Drupal 8 projects!

And it's thanks to its 2 sub-modules that Devel makes a great “ally”: Kint and Web Profiler!


  • it “injects” its Kint Library into your Drupal 8 website and empowers you to print variables in Twig templates using PHP functions (ksm() and kint())
  • using {{ kint(my_variable) }} you get to place the variable into a neatly formatted structure, one hiding/showing their levels of objects/arrays 

Web Profiler

  • it displays a toolbar at the bottom of your Drupal site, one presenting you with useful data about your memory usage, number of queries etc.


3. Debug Your Drupal 8 Projects with Drupal Console

How could I have possibly left out precisely Drupal's powerful CLI that enables you to:

  • generate boilercode to build themes and modules
  • interact with your Drupal installation
  • debug code in your Drupal 8 web project

As you leverage the Symfony Console's power and that of its “cluster” of third-party components, Drupal Console puts a whole “arsenal” of debug commands at your disposal.

Basically, you get to use any command having the term “debug”, yet, allow me to make some recommendations, to point out to you some of the most useful ones:


drupal database:table:debug: show all tables of the database 

drupal config:debug image.settings: show configuration for image.settings 

drupal database:table:debug: show all tables of the database

drupal database:log:debug: display current log events

drupal site:statistics: show some statistics about the website (stats about the enabled/disabled modules, users and comments related stats etc.)

drupal container:debug: display all services ID with the matching class name

drupal config:debug: list all configurations


4. Print Variables Using PHP Functions

Make use of PHP's two more-than-useful functions for printing variables, arrays and objects on-screen:

  1. print_r()
  2. var_dump()

Moreover, Drupal, too, “spoils” you with its own handy function for powering your debugging session with: debug()

5. Use PHPStorm 

And here's the fifth technique for you to debug your Drupal 8 projects (you can't complain that you're short on choice now can you? 

If none of the other 4 method suits your profile as a Drupal programmer (or your current web project's particularities) then there's always this commercial PHP IDE that you could turn into your multi-functional debugging tool.

Where do you add that it integrates perfectly with the Drupal code base and Xdebug!

Speaking of which:

a. Xdebug:

  • take it as a more complex, a more refined debugging technique compared to the a bit more basic, quick-and-easy to use Kint sub-module, for instance. What it does is enable you to add a breakpoint in your PHP code and to step through as a Drupal request is being made.
  • also, using Xdebug you gain easy access to your variables. You get to visualize which ones are available at a certain time.
  • needless to add that you need to figure out how to properly configure Xbug in PHPStorm!

b. Using PHPStorm with Drupal:

  • integrating PHPStorm into your Drupal 8 web projects is more than straightforward: use “drupal” as your search term scanning through the Preferences section (you'll find it right under “PHP”)
  • once enabled, it triggers the autocomplete function for hooks. And this is a “life-saving” convenience! Just think about the time you'd otherwise need to invest/waste trying to remember each and every single hook along with its arguments.

And you get to “refine” your debugging technique even more by installing some extra PHPStorm plugins, as well: PHP Annotations, Symfony Plugin, Drupal Symfony Bridge.

“Supercharged” with these additional plugins, navigating thorough your Drupal 8 site's methods and classes turns into a highly simplified two-step process: you just click on the reference as you keep your command/control pressed!

Note: once you've enabled your newly installed extra plugins, remember to enable “Symfony integration” as well! 

The END! My list of 5 methods for you to debug your Drupal 8 projects ends here. As you can see, you have plenty of options at your disposal, of all “sizes”, all levels of complexity and easiness of use! Which one's your favorite one?