Easy debugging with Laravel breadcrumbs and Honeybadger

If you're building web applications and care about your users, Laravel breadcrumbs can help you debug why you're seeing an error, giving you greater insight into what users are experiencing. It's easy to take advantage of this feature and add breadcrumbs without much extra configuration, especially if you're already using Honeybadger. We're excited to share this feature with you! Here's a quick walkthrough.

How do breadcrumbs help you find problems?

A big part of debugging errors is wondering things like:

• "How did this exception happen?"
• "Why is this value null?"
• "Why is this user ID a String instead of an Integer?"
• "How did this parameter get dropped?"
• "What state is this user in?"
• "What methods were called before this exception was thrown?"

To help with common missing context problems like these, you've probably added extra logs to your app at some point. It's convenient to be able to reference them when something happens.

Log::debug("Processed payment request for $userId");

Log::debug("Sending notification to user $userId on channel $channel");

Logs like these are helpful, but they introduce a new problem to your Laravel project. These sorts of unstructured logs can be noisy and challenging to sort through. Oftentimes in search of making helpful information easier to find, we bury it with less helpful context.

Breadcrumbs let you replace those unstructured debugging logs with structured event records. Say goodbye to painful hours spent scouring log files to find out what was going on at 11:20 PM a few weeks ago. Record these events with Honeybadger, and you'll see the breadcrumbs right in the error detail on your dashboard.

Breadcrumbs associate extra context directly with errors so that you can see more than just an error message. You can send breadcrumbs manually in PHP with the Honeybadger library, and Laravel developers will find many helpful breadcrumbs already included for them.

How to send breadcrumbs to Honeybadger in PHP

Recording a breadcrumb for Honeybadger in your PHP app is pretty straightforward. It's as simple as using the addBreadcrumb() method on the Honeybadger client. You'll call the method with a message and associated context like this:

// Without Laravel
$honeybadger->addBreadcrumb('Sending notification', ['user' => $user->id, 'channel' => $channel]);

// With Laravel
Honeybadger::addBreadcrumb('Sending notification', ['user' => $user->id, 'channel' => $channel]);

If an error occurs at some point in future execution, the breadcrumb will show up in your dashboard like this:

If an error doesn't occur, the information doesn't pollute the rest of your logs. This example is perfect because the breadcrumb indicates what might actually be the cause of the error. Can you spot it?

In the screenshot above, you'll notice that the channel attribute is empty. In the code example, we set that value to $channel. The value being missing might be the cause of our error. While this is somewhat trivial, you can imagine how useful this information can become when displayed right alongside your reported errors.

Automatic Laravel breadcrumbs

Adding breadcrumbs manually is great, but it has one pretty big shortcoming. It requires that you have the foresight to add a breadcrumb where it might be needed without actually knowing you're going to have an error! To an extent, you can intelligently add useful bits of information throughout your codebase as breadcrumbs, but you're still likely to miss some useful information. If you knew you were going to have an error, you wouldn't need the breadcrumb because you would just fix it!

Fortunately for those of us using Laravel, there's a better option for breadcrumbs. If you're using Laravel, we'll automatically capture breadcrumbs for interesting events in your web application. The Honeybadger Laravel library automatically listens for the following events:

• Log messages
• View renders
• Email dispatches
• Job dispatches
• Notification dispatches
• Database queries
• Redis commands
• Incoming requests

All of this can be configured in the config/honeybadger.php configuration file. You can also turn off Breadcrumb collection by setting the breadcrumbs.enabled configuration option the false.

How can you use breadcrumbs in PHP?

Breadcrumbs are currently available in our PHP client as of version 2.8.0, and in our Laravel client as of version 3.8.0. You can update your Honeybadger client by running:

composer update honeybadger-io/honeybadger-laravel

or by running:

composer update honeybadger-io/honeybadger-php

(depending on which you're using.)

What about breadcrumb categories?

Breadcrumbs have categories to help your events be displayed with greater utility. For breadcrumbs you're manually adding, you can add any category, including:

• custom
• error
• query
• job
• request
• render
• log
• notice

The error category is for errors or exceptions that get thrown, and these events will be displayed in red on the dashboard. You can use the custom category or actually create your own category, which will be displayed on the dashboard as if it belonged to the custom category. A Laravel breadcrumb is treated the same as the ones that come from vanilla PHP.

Let us know how it goes!

We hope that breadcrumbs will be a helpful addition to your debugging toolbox. We find them to be a great source of context that pay dividends when debugging particularly tricky errors. With the right versions of the Honeybadger PHP libraries, you can send breadcrumbs in no time.

Try it out, and give our team a shout if there is anything you would like to see added. For Laravel project breadcrumbs, you can get started right away without extra configuration or even sending any events on your own! Be sure to check out our documentation for more details on using breadcrumbs in PHP.