Buy

Debugging in Drupal 8 is pretty sweet... if you now the tools to use.

Turning on Debugging

First, let's activate a debug mode so we can see errors... just in case some other developer makes a mistake and we have to debug it.

In sites/ there's an example.settings.local.php file that can be used to activate development settings locally. But first, we need to play with permissions: Drupal makes some files in this directory readonly for security. Start by making sites/default writable by us:

chmod 755 sites/default

Now, copy sites/example.settings.local.php to sites/default/settings.local.php:

cp sites/example.settings.local.php sites/default/settings.local.php

Finally, make sure we can write to settings.php:

chmod 644 sites/default/settings.php

Tip

On a production server, it's beast to make sure these files are not writeable by whatever user runs your web server.

The settings.local.php file activates several things that are good for debugging, like a verbose error level. It also loads a development.services.yml file that we're going to talk about soon:

92 lines sites/default/settings.local.php
... lines 1 - 31
/**
* Enable local development services.
*/
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
/**
* Show all error messages, with backtrace information.
*
* In case the error level could not be fetched from the database, as for
* example the database connection failed, we rely only on this value.
*/
$config['system.logging']['error_level'] = 'verbose';
... lines 44 - 92

But just having settings.local.php isn't enough! Open settings.php. At the bottom, uncomment out the lines so that this file is loaded:

727 lines sites/default/settings.php
... lines 1 - 701
/**
* Load local development override configuration, if available.
*
* Use settings.local.php to override variables on secondary (staging,
* development, etc) installations of this site. Typically used to disable
* caching, JavaScript/CSS compression, re-routing of outgoing emails, and
* other things that should not happen on development and testing sites.
*
* Keep this code block at the end of this file to take full effect.
*/
if (file_exists(__DIR__ . '/settings.local.php')) {
include __DIR__ . '/settings.local.php';
}
... lines 715 - 727

Of course, we need to rebuild our cache and the Drupal Console in all its wisdom has a command for that:

drupal cache:rebuild

From this command you can clear all kinds of different caches, like the menu cache, render cache or leave it blank to do everything.

Side note: the Drupal Console app is built on top of the Symfony Console library, and you can take advantage of it to create really cool command line scripts like this if you want to. It's one of the best pieces of Symfony.

Back in the browser, if you refresh now, there's no difference: everything is roaring along. But, try deleting the roar() function and refresh. Now we get a nice error that says:

The controller for URI /the/dino/says/50 is not callable.

That's a way of saying "Yo! This route is pointing to a function that doesn't exist!" And when we put the function back and refresh, things are back to a roaring good time.

List all the Routes

Every page of the site - including the homepage and admin areas - has a route. And that leads me to the next natural question: what time is dinner? I mean, can I get a list of every single route in the system? Well, of course! And dinner is at 6.

Once again, go back to the trusty Drupal Console app. To list every route, run router:debug:

drupal router:debug

Wow! This prints every single route in the system, which is wonderful when you're trying to figure out what's going on in a project. This includes the admin route and our custom route.

To get more information about a route, copy it's internal name - that's the part on the left - and pass it as an argument to router:debug. This route has several curly brace routing wildcards that are passed to the getForm method of this controller class. This is pretty sweet, but we can go further!

Leave a comment!

  • 2015-12-22 weaverryan

    Glad to hear it! I use bash and autocompletion (in general) works fine - I haven't hooked up the Drupal Console's auto-completion, however, but I imagine it would work fine (I use autocompletion for Symfony's console, which is accomplished in a similar way).

  • 2015-12-08 weaverryan

    I would try using DrupalConsole to enter debugging mode instead - https://knpuniversity.com/scre.... For some reason, some people are having strange issues after entering debugging mode by including settings.local.php. But I haven't been able to repeat that yet :)

  • 2015-12-08 weaverryan

    Yea there is obviously some weirdness for some machines related to entering the debug mode. This is an excellent alternative (and really easier anyways).

  • 2015-12-02 Pietrino Atzeni

    If I comment out that line, drupal cache:rebuild complains about DRUPAL_ROOT not defined. I think this can be related to my PHP version (that's 5.5.29, on a MAC with El Capitan, installed with brew) but other than that, I don't know where else to dig...

  • 2015-12-02 Pietrino Atzeni

    Mine is 5.5.29.

  • 2015-12-02 Zachary Maximov

    Thanks

  • 2015-12-02 Darryl Norris

    You can enable debugging in D8 by running the command drupal site:mode dev with DrupalConsole.

  • 2015-12-02 Zachary Maximov

    Same problem. What is your PHP version?

  • 2015-12-01 weaverryan

    Hmm, I don't get this with a fresh 8.0.0. install (downloaded from drupal.org/8). This line *does* come from settings.local.php (you'll find mention of this class there), but the class itself is located in core/lib/Drupal/Component/Assertion/Handle.php and should be autoloaded just like everything else. So I'm not so sure about this. Does this information give you any clues?

  • 2015-12-01 Pietrino Atzeni

    Hi, I followed all the steps here, but when I uncomment the lines in settings.php, to include settings.local.php, I get a "Class 'Drupal\Component\Assertion\Handle' not found". I'm using drupal 8.0.0. Any suggestion?