Drupal Debugging Techniques

Introduction

This tutorial covers essential debugging techniques for Drupal, aimed at enhancing your ability to troubleshoot issues effectively. Whether you're a beginner or an experienced developer, mastering these techniques will help you identify and resolve problems in your Drupal site quickly.

Step 1: Displaying Error Messages

To start debugging, you need to see the error messages that Drupal generates. This information is crucial for understanding what might be going wrong.

• Enable Error Reporting:
  • Open your settings.php file located in sites/default/.
  • Find the following line:

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

  • Change it to:

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

• Clear Cache:
  • After updating the settings, clear the cache to apply the changes. You can do this via the admin interface or by running:

    drush cr
    

Step 2: Printing Variables in PHP and Twig Using Devel

The Devel module is a powerful tool for debugging in Drupal, allowing you to print variables easily.

• Install Devel Module:

  • Use Composer to install:

    composer require drupal/devel
    

  • Enable the module:

    drush en devel
    

• Using Devel in PHP:

  • To print a variable, use:

    dpm($variable);
    

  • This will display the variable's contents in a structured format in the messages area.

• Using Devel in Twig:

  • Use the following syntax in your Twig templates:

    {{ dump(variable) }}
    

  • This will output the variable information in the HTML source for easy debugging.

Step 3: Using WebProfiler to Debug

WebProfiler is a built-in tool that provides detailed information about the requests made to your Drupal site.

• Enable WebProfiler:

  • Ensure that the development services are enabled in your services.yml:

    parameters:
      http.response.debug: true
    

• Accessing WebProfiler:

  • Open your site in a browser and append ?XDEBUG_PROFILE to the URL.
  • Check the WebProfiler bar at the bottom of the page for performance metrics, including queries, memory usage, and more.

Step 4: Using Xdebug in PhpStorm

Xdebug is a powerful debugging tool that integrates with PhpStorm, allowing you to step through your code.

• Install Xdebug:

  • Follow the installation instructions for Xdebug based on your PHP version and environment.

• Configure PhpStorm:

  • Go to File > Settings > Languages & Frameworks > PHP > Debug.
  • Set the Debug port to 9000 (or whatever port Xdebug is configured to use).

• Set Up Debugging:

  • Place breakpoints in your code by clicking in the gutter next to the line numbers.
  • Start listening for PHP Debug Connections in PhpStorm.
  • Initiate a debugging session by appending ?XDEBUG_SESSION_START=1 to your browser’s URL.

Conclusion

By following these steps, you can effectively troubleshoot and debug issues in your Drupal site. Remember to enable error reporting, utilize the Devel module for variable inspection, leverage WebProfiler for request insights, and configure Xdebug for a powerful debugging experience in PhpStorm. With these tools and techniques, you'll be better equipped to maintain and improve your Drupal projects.