Debugging!

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00

Debugging in Drupal 8 is pretty sweet... if you know 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 best 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:

... 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:

... 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!

This tutorial is built using Drupal 8.0. The fundamental concepts of Drupal 8 - like services & routing - are still valid, but newer versions of Drupal *do* have major differences.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "composer/installers": "^1.0.21", // v1.0.21
        "wikimedia/composer-merge-plugin": "^1.3.0" // dev-master
    }
}