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
FreeKnowing how to clear Drupal's cache is an important skill for any developer. You'll likely find yourself doing it frequently in order to get Drupal to register the changes you make to your code, or other updates you make via the UI. It is also a good first step to trouble shooting problems with your Drupal site: Clear the cache before you do any other debugging to ensure it's not just a bad cache entry.
Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.
By the end of this tutorial, you should be able to:
- Set up your local Drupal site for theme development
- Prepare your local development environment for working on and debugging themes
Stark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates.
Core Themes: Stark
FreeStark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates. In this tutorial, we'll explore Stark and its primary features and discuss the various reasons for utilizing the Stark theme.
In this tutorial, we'll continue to look under the hood of Drupal 8, this time using a tool bundled with Devel called Webprofiler. You'll learn how to use the web debug toolbar and the profiler. You'll also learn how to reverse engineer a page to find out the names of the controllers responsible for output on that page.
Note: Webprofiler is now a separate project from Devel but still has it as a dependency.
Note: In order to get the Webprofiler timeline view working you need to add some configuration to your settings.php file. See the README.md file included with the Webprofiler module for more information on how to do this.
Additional resources
In this tutorial we're going to use the git bisect command to do a little bit of debugging. We're all human, and sometimes bugs get introduced our software and we may not notice them for a while. Especially on fast moving projects. A good example of this would be a performance regression, and now you want to figure out what commit made everything run slower all of a sudden. Bisect allows us to do a binary search between a known good commit and a known bad commit and quickly narrow down which commit introduced the problem. From there it's much easier to figure out what exactly the problem is and fix it.
Xdebug
TopicDebugging your Drupal codebase can be made substantially easier by learning how to enable and configure the Xdebug PHP extension.
External resources
-
Devel (Drupal.org)
- The Devel module, and its many sub-modules, provide useful tools for debugging, and understanding, Drupal code.
-
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.
- 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.
-
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.