Topic

Debug Drupal Code

  
Last updated August 23, 2017
ThemingModule DevelopmentDrupal 8Drupal 7Drupal 6

Debugging is one part tools, and one part process.

Debugging tools can help you gather additional information about the state and context of your application when performing different tasks. There are generally two reasons that you're interested in tools for debugging Drupal: either your site or some specific feature isn't working, or you're ready to take a peek behind the curtain and learn more about how a specific feature works.

Knowing what to look for, and where to start looking, requires practice and a methodical approach. As you become more familiar with Drupal, debugging will become faster and easier as you'll recognize common symptoms and know how to treat them.

Additionally, we firmly believe that stepping through the code using tools like a debugger or analyzing what your code is doing with a profiler is one of the best ways to truly understand Drupal's APIs.

Example tasks

  • Figure out why your Drupal site is displaying a white screen of death
  • Locate problems in code so that you can fix them
  • Learn how a feature or API in Drupal works by stepping through the code as it executes

Confidence

New tools to assist with debugging will continue to be developed. At the same time, existing tools are unlikely to become irrelevant anytime soon--especially those that are not Drupal-specific.

Drupalize.Me resources

  • Clear Drupal's Cache
    • Before you do anything else, clear the cache, and then confirm the issue is still present afterwards.
  • Configure Your Environment for Theme Development
    • Learn how to disable caching and turn on Twig's debug mode in order to make finding issues in a theme easier.
  • Install Webprofiler and Identify Controllers
    • Get an overview of the Webprofiler module. It's part of the Devel module that allows you to profile requests and analyze routes, memory use, database queries, and much more. It's useful for getting more information about what's going on when Drupal services a request.
  • Debugging in PhpStorm
    • Learn how to use the debugger in PhpStorm in conjunction with Xdebug to set breakpoints and debug any PHP application including Drupal. Pro tip: you really should set up Zero-configuration debugging.
  • Using Git Bisect
    • The git-bisect command is a powerful way to quickly search through the history of a Git repository for the commit that introduced a bug.
  • Learning to Debug: Stop Making Assumptions and Learning to Debug: Stop Thinking and Look
    • These blog posts look at some of the things we can do improve our own debugging skills regardless of which tools are being used.
  • Devel topic and Xdebug topic
    • These two tools have been the standard for debugging Drupal for a long time.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Drupal 8 User Guide: Preventing and Fixing Problems (drupal.org)
    • This chapter contains information on clearing Drupal's cache, analyzing Drupal's logs, and checking your site's status report. All three tools let you gather more information about a problem.
  • Devel (drupal.org)
    • The Devel module, and its many sub-modules, provide useful tools for debugging, and understanding, Drupal code.
  • Drupal Console (drupalconsole.com)
    • The Drupal Console command line application has a number of helpful debug:* commands. It's particularly useful for introspecting a specific Drupal site.
  • Xdebug (phptherightway.com)
    • Xdebug is a PHP extension, and the tool of choice, for setting breakpoints and stepping through PHP code as it is executed. Download from https://xdebug.org/.
    • Our recommendation: bite the bullet and figure out how to use Xdebug; it'll save time and make you a better developer.
  • Drupal 8 Debugging Techniques (webwash.net)
    • Experienced Drupal developer Ivan Zugec demonstrates various Drupal debugging tools including Kint, Webprofiler, Xdebug, Drupal console, and more. Includes live demonstrations that'll give you a good idea of each tool's functions.
  • Dark Art of Debugging - php[tek] (youtube.com)
    • This presentation from php[tek] by our own Joe Shindelar lays out a tools-independent approach for methodically locating bugs in software. Useful for practicing and getting better at debugging.
  • Become a Better Developer with Debugging Techniques for Drupal (youtube.com)
    • This webinar provides some good advice on where and what to look for when debugging. It's useful for any developer, but especially relevant given its Drupal context.
  • Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems, by David J. Agans (amazon.com)
    • A book that teaches how to approach debugging using methodical analysis in order to be a more efficient and better developer.